跳到主要内容

查询语法

UnderControl 提供了强大的 SQL 风格查询语法，用于过滤和搜索任务。你可以手动编写查询，也可以让 AI 根据自然语言自动生成。

查询的使用场景​

查询语法在整个应用中通用：

  • 高级搜索 — 在搜索页面构建复杂的过滤条件
  • 自定义视图 — 定义视图的 Root Query，筛选显示的任务
  • 看板过滤 — 在看板列中过滤任务
  • 保存的查询 — 保存常用查询，一键执行
  • CLI — 在终端中使用 ud task query 运行查询
  • AI 聊天 — 用自然语言描述需求，让 AI 生成查询
不想手写查询？

使用任务页面的 AI 聊天功能 — 直接用自然语言描述你的需求，AI 会帮你生成查询语句。Web 界面和 CLI（ud task nlquery）都支持此功能。

快速开始​

以下是几个入门查询示例：

-- 查找所有待办任务
status = 'todo'

-- 查找逾期任务
deadline < 'today' AND status != 'done'

-- 按标题搜索任务
title ILIKE '%会议%'

-- 最近一周创建的任务，按最新排序
created_at >= '-7d' ORDER BY created_at DESC

可用字段​

内置字段​

字段类型说明
title文本任务标题
description文本任务描述
status文本任务状态：todo、in-progress、done、archived
tags数组任务的标签列表
deadline日期时间截止日期
created_at日期时间创建时间
updated_at日期时间最后修改时间

自定义字段​

自定义字段使用 cf. 前缀进行查询，前缀后跟自定义字段的名称（slug）。

cf.priority = 5
cf.priority > 3
cf.priority IN (1, 2, 3)
cf.department = 'engineering'

自定义字段类型​

每种自定义字段类型支持特定的运算符：

类型说明支持的运算符
数字（number）数值字段=、!=、>、<、>=、<=、IN、IS NULL、IS NOT NULL
文本（text）文本字段=、!=、LIKE、ILIKE、IN、IS NULL、IS NOT NULL
选择（select）下拉选择=、!=、IN、IS NULL、IS NOT NULL
复选框（checkbox）布尔值=、!=、IS NULL、IS NOT NULL
用户（user）用户引用=、!=、IN、IS NULL、IS NOT NULL
自定义字段名称

自定义字段名称是你创建字段时定义的 slug。例如，如果你创建了一个名为"优先级"的字段，其 slug 可能是 priority_level，查询时应写作 cf.priority_level。

运算符​

比较运算符​

等于和不等于​

运算符说明示例
=等于status = 'todo'
!=不等于status != 'archived'

数值和日期比较​

运算符说明示例
>大于deadline > 'today'
<小于deadline < 'today'
>=大于等于created_at >= '-7d'
<=小于等于deadline <= 'tomorrow'

这些运算符适用于日期时间字段、数字类型的自定义字段和标准日期值。

空值检查​

运算符说明示例
IS NULL字段没有设置值deadline IS NULL
IS NOT NULL字段已设置值deadline IS NOT NULL

使用空值检查可以查找可选字段（如截止日期或自定义字段）为空或已填写的任务。

文本搜索运算符​

运算符说明示例
LIKE模式匹配（区分大小写）title LIKE '%Bug%'
ILIKE模式匹配（不区分大小写）title ILIKE '%bug%'

使用 % 通配符匹配任意字符序列：

模式匹配规则
'%会议%'包含"会议"的任何位置
'会议%'以"会议"开头
'%会议'以"会议"结尾
提示

ILIKE 通常是更好的选择，因为它不区分大小写。只有在需要严格区分大小写时才使用 LIKE。

多值运算符​

IN​

检查字段值是否在给定列表中：

status IN ('todo', 'in-progress')
cf.department IN ('engineering', 'design', 'marketing')

CONTAINS_ALL（数组字段）​

检查数组字段是否包含所有指定值，主要用于 tags 字段：

-- 同时包含 'work' 和 'urgent' 标签的任务
tags CONTAINS_ALL ('work', 'urgent')

BETWEEN​

检查值是否在范围内（包含边界值）：

deadline BETWEEN '2024-01-01' AND '2024-12-31'
created_at BETWEEN '-7d' AND 'today'
cf.estimate BETWEEN 5 AND 20

日期时间表达式​

日期时间字段（deadline、created_at、updated_at）除了支持标准的 ISO 8601 日期格式（如 2024-01-15），还支持多种便捷的日期表达式。

命名表达式​

表达式说明
today今天的开始时间（零点）
yesterday昨天的开始时间
tomorrow明天的开始时间
now当前精确时间（日期 + 时间）

相对表达式​

相对表达式允许你指定相对于当前时间的时间点。使用 - 表示过去，+ 表示未来：

格式说明示例
-Nd 或 -NdaysN 天前-7d = 7 天前
+Nd 或 +NdaysN 天后+3d = 3 天后
-Nw 或 -NweeksN 周前-2w = 2 周前
+Nw 或 +NweeksN 周后+1w = 1 周后
-Nm 或 -NmonthsN 月前-1m = 1 个月前
+Nm 或 +NmonthsN 月后+3m = 3 个月后
-Ny 或 -NyearsN 年前-1y = 1 年前

日期时间示例​

-- 截止日期在今天或之前
deadline <= 'today'

-- 最近 7 天创建的任务
created_at >= '-7d'

-- 本周更新的任务
updated_at >= '-1w' AND updated_at <= 'today'

-- 未来一周内到期的任务
deadline BETWEEN 'today' AND '+7d'

-- 未来一个月内到期的任务
deadline BETWEEN 'today' AND '+1m'

-- 在特定年份创建的任务
created_at BETWEEN '2024-01-01' AND '2024-12-31'
标准日期格式

你也可以使用标准的 ISO 8601 日期格式，如 2024-01-15 或 2024-01-15T14:30:00Z。当你需要查询特定的固定日期而非相对日期时，这些格式非常有用。

逻辑运算符​

AND 和 OR​

使用 AND 和 OR 组合多个条件：

-- 两个条件都必须为真
status = 'todo' AND deadline <= 'today'

-- 任一条件为真即可
status = 'done' OR status = 'archived'

运算符优先级​

AND 的优先级高于 OR，即 AND 条件会先被计算。

以下查询：

status = 'todo' OR pinned = 'true' AND deadline <= 'today'

等同于：

status = 'todo' OR (pinned = 'true' AND deadline <= 'today')

使用括号​

使用括号明确控制计算顺序：

-- 待办或进行中的任务，并且今天到期
(status = 'todo' OR status = 'in-progress') AND deadline <= 'today'

-- 今天到期或标记为紧急的任务，并且未完成
(deadline <= 'today' OR tags = 'urgent') AND status != 'done'

-- 嵌套分组
(status = 'todo' AND deadline <= 'today') OR (status = 'in-progress' AND tags = 'urgent')
提示

在同一查询中混合使用 AND 和 OR 时，建议始终使用括号来明确你的意图 — 即使在不严格需要的情况下也是如此。这会让查询更易读，也能避免因优先级规则产生意外结果。

ORDER BY 排序​

使用 ORDER BY 子句对查询结果进行排序，它始终放在查询的末尾。

-- 按创建时间倒序排列所有结果
ORDER BY created_at DESC

-- 过滤并排序
status = 'todo' ORDER BY created_at DESC

-- 逾期任务按截止日期排序（最早的在前）
deadline < 'today' AND status != 'done' ORDER BY deadline ASC

可排序字段​

字段说明
created_at按创建时间排序
updated_at按最后更新时间排序
deadline按截止日期排序
title按标题字母顺序排序

排序方向​

方向说明
ASC升序 — 从小到大、从早到晚、A 到 Z
DESC降序 — 从大到小、从晚到早、Z 到 A

如果不指定方向，默认为 DESC（降序）。

保存的查询​

保存的查询功能让你可以存储常用查询，实现一键快速访问。无需每次都重新输入相同的查询，你可以为其命名并保存。

功能特点​

  • 创建 — 为任何查询保存一个描述性名称
  • 执行 — 运行保存的查询，直接查看匹配的任务
  • 编辑 — 更新保存查询的名称或查询语句
  • 置顶 — 将重要的查询固定到列表顶部，快速访问
  • 排序 — 拖拽调整保存查询的顺序
  • 删除 — 移除不再需要的查询

使用方法​

  1. 从侧边栏导航到保存的查询页面
  2. 点击新建查询创建一个保存的查询
  3. 输入名称（如"我的逾期任务"）和查询语句
  4. 点击保存的查询即可展开查看匹配结果
  5. 置顶常用查询，保持它们在列表顶部

保存查询示例​

名称查询语句
逾期任务deadline < 'today' AND status != 'done' AND status != 'archived'
本周到期deadline BETWEEN 'today' AND '+7d' AND status != 'done'
近期活跃updated_at >= '-7d' AND status IN ('todo', 'in-progress')
紧急事项(deadline <= 'today' OR tags = 'urgent') AND status != 'done'
未规划任务deadline IS NULL AND status = 'todo'

在 CLI 中使用查询​

UnderControl CLI 支持直接在终端运行查询。这对于脚本编写、自动化和快速查找非常有用，无需离开终端工作流。

ud task query​

使用上述文档中的结构化查询语法运行查询：

ud task query "<查询语句>" [选项]

选项：

  • --page — 页码（默认：1）
  • --limit — 每页条数（默认：50）
  • --sort — 排序字段（title、deadline、created_at、updated_at）
  • --order — 排序方向（asc、desc）

示例：

# 查找所有待办任务
ud task query "status = 'todo'"

# 按标题搜索
ud task query "title ILIKE '%api%'"

# 本周到期的任务
ud task query "deadline BETWEEN 'today' AND '+7d'"

# 带标签的任务
ud task query "tags = 'urgent'"

# 复杂查询并排序
ud task query "(status = 'todo' OR status = 'in-progress') AND deadline <= 'today'" --sort deadline --order asc

# 分页查询
ud task query "status != 'archived'" --page 2 --limit 20

ud task nlquery​

使用自然语言查询任务 — AI 会将你的请求翻译为结构化查询：

ud task nlquery "<自然语言描述>"
ud task nl "<自然语言描述>"  # 简写别名

示例：

ud task nlquery "显示逾期任务"
ud task nlquery "标记为 work 标签的未完成任务"
ud task nlquery "查找标题中包含报告的任务"
ud task nlquery "最近一周创建的任务"
ud task nlquery "本月到期的高优先级任务"
信息

自然语言查询功能需要配置 AI 服务。AI 会解析你的请求并生成对应的结构化查询，然后执行查询。

完整的 CLI 文档请参阅 CLI 参考。

AI 驱动的查询​

UnderControl 集成了 AI 功能，让查询更加便捷。你无需学习查询语法，直接用自然语言描述需求即可。

在 Web 界面中​

  1. 打开任务页面
  2. 打开 AI 聊天面板
  3. 用自然语言输入你的请求，例如：
    • "显示所有逾期的任务"
    • "查找标记为 work 标签且本周到期的任务"
    • "今天更新了哪些任务？"
  4. AI 会生成并执行结构化查询

在 CLI 中​

使用 ud task nlquery（或其简写 ud task nl）：

ud task nlquery "这周我需要做的任务"

AI 能理解上下文和意图，所以你可以使用日常用语。它会将你的请求翻译为结构化查询语法并返回匹配的任务。

实用示例​

按状态筛选​

-- 所有待办任务
status = 'todo'

-- 进行中的任务
status = 'in-progress'

-- 已完成的任务
status = 'done'

-- 所有未完成的任务（待办或进行中）
status IN ('todo', 'in-progress')

-- 非归档任务
status != 'archived'

按截止日期筛选​

-- 今日到期或已逾期的未完成任务
deadline <= 'today' AND status != 'done' AND status != 'archived'

-- 逾期任务
deadline < 'today' AND status != 'done' AND status != 'archived'

-- 本周到期
deadline BETWEEN 'today' AND '+7d' AND status != 'done'

-- 本月到期
deadline BETWEEN 'today' AND '+30d' AND status != 'done'

-- 未设置截止日期
deadline IS NULL

-- 已设置截止日期
deadline IS NOT NULL

-- 没有截止日期的待办任务
deadline IS NULL AND status = 'todo'

按时间筛选​

-- 最近 7 天创建的
created_at >= '-7d'

-- 最近 7 天更新的
updated_at >= '-7d'

-- 本月创建的
created_at >= '-30d'

-- 今天更新的
updated_at >= 'today'

-- 在特定日期范围内创建的
created_at BETWEEN '2024-06-01' AND '2024-06-30'

按标签筛选​

-- 包含特定标签的任务
tags = 'work'

-- 包含任一标签的任务
tags IN ('work', 'personal')

-- 包含所有指定标签的任务
tags CONTAINS_ALL ('work', 'urgent')

文本搜索​

-- 标题包含关键词（不区分大小写）
title ILIKE '%会议%'

-- 描述包含关键词
description ILIKE '%重要%'

-- 标题以特定词开头
title ILIKE 'bug%'

-- 区分大小写的标题搜索
title LIKE '%API%'

自定义字段​

-- 数字自定义字段比较
cf.priority > 5
cf.estimate >= 10
cf.priority BETWEEN 1 AND 3

-- 文本/选择自定义字段
cf.department = 'engineering'
cf.department IN ('design', 'marketing')

-- 复选框自定义字段
cf.reviewed = 'true'

-- 自定义字段的空值检查
cf.priority IS NULL                           -- 尚未设置优先级
cf.priority IS NOT NULL AND cf.priority <= 3  -- 低优先级任务

组合查询​

-- 紧急待办：今日到期或标记为紧急，且未完成
(deadline <= 'today' OR tags = 'urgent') AND status != 'done' AND status != 'archived'

-- 工作进行中：带 work 标签的进行中任务
tags = 'work' AND status = 'in-progress'

-- 近期活跃：最近 7 天更新的未完成任务
updated_at >= '-7d' AND status IN ('todo', 'in-progress')

-- 需要关注：逾期或本周到期的待办任务
(deadline < 'today' OR deadline BETWEEN 'today' AND '+7d') AND status = 'todo'

-- 高优先级工程任务
cf.priority > 5 AND cf.department = 'engineering' AND status != 'done'

-- 未规划的紧急任务
deadline IS NULL AND tags = 'urgent' AND status = 'todo'

带排序的查询​

-- 待办任务，最新的在前
status = 'todo' ORDER BY created_at DESC

-- 逾期任务，最早的截止日期在前
deadline < 'today' AND status != 'done' ORDER BY deadline ASC

-- 最近更新的任务
status != 'archived' ORDER BY updated_at DESC

-- 高优先级按更新时间排序
cf.priority > 5 ORDER BY updated_at DESC

-- 所有任务按标题字母排序
ORDER BY title ASC

提示与注意事项​

  1. 字符串值需要引号 — 所有字符串值必须用单引号（'todo'）或双引号（"todo"）包围。数字不需要引号。

  2. 字段名区分大小写 — 始终使用小写字段名：status、deadline、created_at 等。

  3. 有效的状态值 — 内置的状态值为：todo、in-progress、done、archived。

  4. 数组字段行为 — tags 字段是数组类型。使用 = 检查是否包含某个标签，使用 IN 检查是否包含任一标签，使用 CONTAINS_ALL 要求包含所有指定标签。

  5. 自定义字段前缀 — 查询自定义字段时必须使用 cf. 前缀：cf.priority = 5，而不是 priority = 5。

  6. ORDER BY 位置 — ORDER BY 子句必须始终放在查询的最后部分，所有过滤条件都应在其之前。

  7. 默认排序方向 — 如果省略 ASC 或 DESC，默认排序方向为 DESC（降序）。

  8. 日期格式 — 查询引擎支持 ISO 8601 日期（2024-01-15）、命名表达式（today、tomorrow）和相对表达式（-7d、+1m）。相对表达式需要加引号：'-7d'，而非 -7d。

  9. 可排序字段 — ORDER BY 仅支持以下字段：created_at、updated_at、deadline、title。其他字段不能用于排序。

  10. 空查询 — 你可以单独使用 ORDER BY 而不加任何过滤条件来排序所有任务：ORDER BY deadline ASC。