# ONESQL筛选

URL: https://docs.ones.cn/ones-project/issues/onesql-filter

# 1介绍

ONESQL 用于构建结构化的查询来筛选工作项，它允许用户通过类似 SQL 的语句配置筛选条件，以更灵活地获取目标工作项数据。相比基础筛选器，ONESQL 可以表达更复杂的条件逻辑，能够帮助研发团队提升信息检索效率，支持更精细、更复杂的业务数据查询场景。

![ONESQL筛选 配图 1](https://docs.ones.cn/assets/images/6efd3003ca89d469-90a5d7847761b3cf87ef1e7cdbe3790b.png)

# 2功能入口

在特定产品模块的工作项视图内，可以点击「筛选」按钮，切换到「ONESQL」tab，在 ONESQL 编辑器内输入语句、进行工作项查询。

具体支持 ONESQL 筛选方式的模块如下：

- 我的工作台
- 筛选器
- 临时筛选器
- 项目管理-「筛选器」组件
- 项目管理-「工作项类型」组件
- 项目管理-「迭代」组件
- 未规划工作项筛选器
- 所有工作项筛选器
- 工作项类型筛选器
- 筛选器
- 工作项详情页
- 关联工作项弹窗
- 规划发布内容弹窗
![ONESQL筛选 配图 2](https://docs.ones.cn/assets/images/030fc0a212b6418a-ecc47a26a20a07748b727edf3604f5fa.png)

请注意，其他模块的视图暂时不支持 ONESQL 筛选方式。

# 3语法介绍

### 3.1认识ONESQL语法

ONESQL 查询语句通常由属性字段、运算符、值或函数组成，多个语句之间可以通过关键词组合，构建复杂条件。

- 属性字段（Field）工作项的系统字段或自定义字段，例如「标题」、「状态」、「负责人」、「截止日期」。
- 运算符（Operator）用于比较字段与条件，例如 =、!=、>、<、IN、IS 等。运算符是连接属性和值的桥梁，确保查询结果符合预期条件。
- 关键词（Keyword）用于逻辑组合和控制，例如 AND、OR、NOT。通过关键词可以拼接多个查询语句，构建复杂的逻辑关系。
- 函数（Function）表现为函数名加括号，例如 now()、currentUser()、DepartmentOf()。函数用于动态计算或引用特定对象（如时间、用户、部门），增强语句灵活性。
例如，现在有这样一个查询：

![ONESQL筛选 配图 3](https://docs.ones.cn/assets/images/cf5cf9cb8c275572-e9043d0f35b3be128b5bb9263d1d41f1.png)

这个查询语句对应的语法元素如下：

![ONESQL筛选 配图 4](https://docs.ones.cn/assets/images/1f2a2ba3ba7f9360-9e7109f3112a52304394fe5039a5c765.png)

这个查询语句的含义是，查找「负责人」不是当前用户、且「状态」不包含「已关闭」的工作项。

让我们再看一些实际例子：

```sql
所属项目 == 研发管理
```

此查询查找「所属项目」为「研发管理」的工作项，查询语句中包含属性「所属项目」、运算符 == 和值研发管理。

```sql
所属项目 != 研发管理 AND 负责人 == currentUser()
```

此查询查找「所属项目」不是「研发管理」、且「负责人」是当前用户的工作项，查询语句使用了属性「所属项目」、「负责人」，运算符 !=、==、关键词 AND 和函数 currentUser()。

### 3.2运算符

运算符是 ONESQL 中用于建立属性与条件之间比较关系的符号，例如 =、!=、>、IN、IS。

#### 运算符说明

ONESQL 支持以下运算符：

| 运算符类型 | 运算符 | 运算符说明 | 实际举例 |
| --- | --- | --- | --- |
| 比较运算符 | < | 小于：X1<X2<br>X1：数字/日期/时间类型的属性 | 查找截止日期早于 2008-12-31 上午 9:00 的工作项<br>截止日期 < "2008/12/31 09:00" |
|  | <= | 小于等于：X1<=X2<br>X1：数字/日期/时间类型的属性 | 查找截止日期不晚于 2008-12-31 上午 9:00 的工作项<br>截止日期 <= "2008/12/31 09:00" |
|  | > | 大于：X1>X2<br>X1：数字/日期/时间类型的属性 | 查找截止日期晚于 2008-12-31 上午 9:00 的工作项<br>截止日期 > "2008/12/31 09:00" |
|  | >= | 大于等于：X1>=X2<br>X1：数字/日期/时间类型的属性 | 查找截止日期不早于 2008-12-31 上午 9:00 的工作项<br>截止日期 >= "2008/12/31 09:00" |
|  | == | 等于：X1 == X2<br>X1：数字/日期/时间/选择/工作项/成员/文本类型的属性<br>该运算符后，仅支持输入单个值 | 查找截止日期是 2008-12-31 上午 9:00 的工作项<br>截止日期 == "2008/12/31 09:00" |
|  | != | 不等于：X1 != X2<br>X1：数字/日期/时间/选择/工作项/成员/文本类型的属性<br>该运算符后，仅支持输入单个值 | 查找截止日期不是 2008-12-31 上午 9:00 的工作项<br>截止日期 != "2008/12/31 09:00" |
| 集合运算符 | IN | 包含<br>X IN (X1, X2, X3, …… Xn)<br>X：数字/日期/时间/选择/工作项/成员类型的属性 | 查找优先级为 P0 或者 P1 的工作项：<br>优先级 in (P0, P1) |
|  | NOT IN | 不包含<br>X NOT IN (X1, X2, X3, …… Xn)<br>X：数字/日期/时间/选择/工作项/成员类型的属性 | 查找优先级不是 P0 也不是 P1 的工作项：<br>优先级 not in (P0, P1) |
| 空值判断运算符 | IS | 是<br>X is EMPTY<br>X：数字/日期/时间/选择/工作项/成员/文件/文本的属性 | 查找没有关联发布的工作项<br>关联发布 is empty |
|  | IS NOT | 不是<br>X is not EMPTY<br>X：数字/日期/时间/选择/工作项/成员/文件/文本的属性 | 查找有所属迭代的工作项<br>所属迭代 is not empty |
| 字符串匹配运算符 | ~ | 包含<br>X ~ "X1"<br>X：文本类型的属性 | 查找标题里包含"小蓝"的工作项<br>标题 ~ "小蓝" |
|  | !~ | 不包含<br>X !~ "X1"<br>X：文本类型的属性 | 查找标题里不包含"小蓝"的工作项<br>标题 !~ "小蓝" |

在 ONESQL 编辑器中，输入属性后，语法补全卡片会主动展示该属性支持的运算符。若需要进一步了解具体运算符用法，可以悬停在该运算符选项上，查看详细说明。

![ONESQL筛选 配图 5](https://docs.ones.cn/assets/images/7ed715de2ebd1d69-d19c40fe3b8ee60e39554381e7023055.png)

#### 运算符优先级规则

在复杂的 ONESQL 语句中，可以通过括号来控制运算符的优先级：

- 有括号时：括号内的条件优先计算。
- 无括号时：AND 的优先级高于 OR，语句将从左到右依次计算。
示例：

```sql
(状态 == 已完成 AND 所属项目 == SysAdmin) OR 负责人 == 张三
```

此语句会先查找 SysAdmin 项目中所有已完成的工作项，再将结果与负责人是张三的工作项合并。

建议在复杂语句中始终使用括号，避免逻辑歧义。

### 3.3函数

针对业务中高频的筛选场景，ONESQL 提供了已封装好筛选逻辑的函数，每个函数都有特定的功能，比如 DepartmentOf() 用来引用和查找部门，EndOfDay() 用来获取时间等。

ONESQL 提供的函数如下：

| 使用场景 | 函数 | 入参说明 | 使用方法 | 示例 |
| --- | --- | --- | --- | --- |
| 筛选时间日期类型的属性 | now(X) | X：字符串，支持 `(+/-)nn(y\|M\|w\|d\|h\|m)`<br>+/-：正负偏移，若省略则默认为 +<br>nn：整数<br>单位：y：年；M：月；w：周；d：天（默认单位）；h：小时；m：分钟 | 获取当前时间 | 创建时间晚于昨天的工作项：<br>创建时间 > now(-1d) |
|  | StartOfDay(X) | X：修饰字符串， `(+/-)nn(y\|M\|w\|d\|h\|m)`<br>+/-：正负偏移，若省略则默认为 +<br>nn：整数<br>单位：y：年；M：月；w：周；d：天（默认单位）；h：小时；m：分钟 | 计算当天开始的时间（当天 00:00:00）增加 X1（当 X1 为正）或减少 X1（当 X1 为负）后的时间 | 查找过去三天内创建的工作项<br>创建日期 > StartOfDay(-3d) |
|  | StartOfWeek(X) | X：修饰字符串， `(+/-)nn(y\|M\|w\|d\|h\|m)`<br>+/-：正负偏移，若省略则默认为 +<br>nn：整数<br>单位：y：年；M：月；w：周（默认单位）；d：天；h：小时；m：分钟 | 计算本周开始的时间（开始日的 00:00:00）增加 X1（当 X1 为正）或减少 X1（当 X1 为负）后的时间 | 查找上周内创建的工作项<br>创建日期 > StartOfWeek(-1) AND 创建日期 < StartOfWeek() |
|  | StartOfMonth(X) | X：修饰字符串， `(+/-)nn(y\|M\|w\|d\|h\|m)`<br>+/-：正负偏移，若省略则默认为 +<br>nn：整数<br>单位：y：年；M：月（默认单位）；w：周；d：天；h：小时；m：分钟 | 计算本月开始的时间（本月一号的 00:00:00）增加 X1（当 X1 为正）或减少 X1（当 X1 为负）后的时间 | 查找上月以来创建的工作项<br>创建日期 > StartOfMonth(-1) |
|  | StartOfYear(X) | X：修饰字符串， `(+/-)nn(y\|M\|w\|d\|h\|m)`<br>+/-：正负偏移，若省略则默认为 +<br>nn：整数<br>单位：y：年（默认单位）；M：月；w：周；d：天；h：小时；m：分钟 | 计算今年开始的时间（今年 1 月 1 号的 00:00:00）增加 X1（当 X1 为正）或减少 X1（当 X1 为负）后的时间 | 查找今年以来创建的工作项<br>创建日期 > StartOfYear |
|  | EndOfDay(X) | X：修饰字符串， `(+/-)nn(y\|M\|w\|d\|h\|m)`<br>+/-：正负偏移，若省略则默认为 +<br>nn：整数<br>单位：y：年；M：月；w：周；d：天（默认单位）；h：小时；m：分钟 | 计算当天结束的时间（当天 23:59:59）增加 X1（当 X1 为正）或减少 X1（当 X1 为负）后的时间 | 查找明天结束前截止的工作项目：<br>截止日期 < EndOfDay(+1) |
|  | EndOfWeek(X) | X：修饰字符串， `(+/-)nn(y\|M\|w\|d\|h\|m)`<br>+/-：正负偏移，若省略则默认为 +<br>nn：整数<br>单位：y：年；M：月；w：周（默认单位）；d：天；h：小时；m：分钟 | 计算本周结束的时间（本周结束日的 23:59:59）增加 X1（当 X1 为正）或减少 X1（当 X1 为负）后的时间 | 查找下周末截止的工作项目<br>截止日期 < EndOfWeek(+1) |
|  | EndOfMonth(X) | X：修饰字符串， `(+/-)nn(y\|M\|w\|d\|h\|m)`<br>+/-：正负偏移，若省略则默认为 +<br>nn：整数<br>单位：y：年；M：月（默认单位）；w：周；d：天；h：小时；m：分钟 | 计算本月结束的时间（月末那天的 23:59:59）增加 X1（当 X1 为正）或减少 X1（当 X1 为负）后的时间 | 查找下个月 15 号之前截止的工作项<br>截止日期 < EndOfMonth(+15d) |
|  | EndOfYear(X) | X：修饰字符串， `(+/-)nn(y\|M\|w\|d\|h\|m)`<br>+/-：正负偏移，若省略则默认为 +<br>nn：整数<br>单位：y：年（默认单位）；M：月；w：周；d：天；h：小时；m：分钟 | 计算今年结束的时间（今年 12 月 31 日的 23:59:59）增加 X1（当 X1 为正）或减少 X1（当 X1 为负）后的时间 | 查找明年三月底前截止的工作项<br>截止日期 < EndOfYear(+3M) |
| 筛选成员类型的属性 | DepartmentOf(X) | X 是部门的名称，支持输入多个部门 | 获取特定部门内的成员 | 查找产品部门、研发部门成员负责的工作项<br>负责人 in DepartmentOf(产品部门，研发部门) |
|  | GroupOf(X) | X 是用户组的名称，支持输入多个用户组 | 获取特定用户组内的成员 | 查找测试用户组里成员负责的工作项<br>负责人 in GroupOf(测试) |
|  | RolesOf(X) | X 是角色的名称，支持输入多个角色 | 获取特定角色包含的成员 | 查找 CDT 小组成员负责的工作项<br>负责人 in RolesOf(CDT小组) |
|  | currentUser() | 无入参 | 获取当前用户 | 查找分配给自己的工作项<br>负责人 = currentUser() |
| 筛选单选级联属性、多选级联属性、所属模块属性 | expand(X) | X 是节点属性值，支持输入多个属性值 | 查找属性某个节点及该节点下的所有子节点 | 查询级联属性"位置"的值包含"江苏省"、"浙江省"的工作项<br>位置 in (江苏省, 浙江省)<br>包含江苏省、浙江省下的所有节点选项值<br>位置 in expand(江苏省, 浙江省) |

和运算符一样，在编辑 ONESQL 语句时，可以通过自动补全卡片查看函数的具体用法。当输入属性、运算符后，自动补全卡片会展示当前属性支持使用的函数。

![ONESQL筛选 配图 6](https://docs.ones.cn/assets/images/20e2fa0966dcc24b-72515232abd6100569a6c85acd3fea45.png)

### 3.4关键词

目前 ONESQL 语法支持的逻辑关键字包括：

- AND：且
- OR：或
- NOT：非
- EMPTY：为空

# 4使用ONESQL筛选

### 4.1场景示例

ONESQL 筛选的操作都在编辑器内完成，以下场景列举了常见的筛选诉求对应的 ONESQL 语句，实际属性因业务场景而异，但是查询语句的整体逻辑和结构不变。

- 场景一：找出分配给自己的未完成任务

```sql
负责人 == currentUser() AND 状态类型 != 已完成
```

- 场景二：查询上周内创建的缺陷

```sql
工作项类型 == 缺陷 AND 创建时间 > StartOfWeek(-1) AND 创建时间 < StartOfWeek()
```

- 场景三：筛选产品部成员负责的需求

```sql
工作项类型 == 需求 AND 负责人 in DepartmentOf(产品部)
```

- 场景四：查找即将在下月 15 日前到期的任务

```sql
截止日期 < EndOfMonth(+15d)
```

### 4.2基础筛选和ONESQL切换

对于已经配置了筛选条件的基础筛选器，可以带条件一键切换到 ONESQL 模式下，并在 ONESQL 编辑器内继续维护筛选条件。

![ONESQL筛选 配图 7](https://docs.ones.cn/assets/images/54a1499d98465bf4-8f092262c491bf375189e75c9be7a87d.png)

点击「应用基础筛选条件」，即可复制当前视图的基础筛选条件，并自动填充到编辑器内

![ONESQL筛选 配图 8](https://docs.ones.cn/assets/images/4477ee6d46198491-7e502c34274ba8bf83292f732f71fe93.png)

填充后效果如下，用户可以继续编辑语句、完成视图筛选。

![ONESQL筛选 配图 9](https://docs.ones.cn/assets/images/336931d5753bcbf8-76d23987ac5fba667c09c37966ea25d7.png)

# 5常见问题

1. ONESQL 语法中的英文区分大小写吗？
- ONESQL 语法中的逻辑关键词、运算符、函数均不区分英文大小写
2. 我写好了 ONESQL 语句，但是提示有错误，如何看到 ONESQL 语句错在哪里？
- ONESQL 报错信息会在行内和编辑器底部展示。
- 查看行内的错误信息时，需要鼠标悬停在错误处
![ONESQL筛选 配图 10](https://docs.ones.cn/assets/images/a7d65e58f98e6203-b5424ed5f5b03092957217f8bda93f49.png)

1. 查询属性值时，有什么格式规则？
1. 查询日期类型属性时，支持的格式是：
- `yyyy/MM/dd HH:mm`
- 例如 `2012/11/12 12:00`
- `yyyy-MM-dd HH:mm`
- 例如 `2012-11-12 12:00`
- `yyyy/MM/dd`
- 例如 `2012/11/12`
- `yyyy-MM-dd`
- 例如 `2012-11-12`
2. 查询间隔时间、停留时间类型的属性时，支持的格式是：
- `(+/-){{整数}}d{{整数}}h{{整数}}m`
- 例如 `+1d2h3m` ，代表时间长度是一天两小时三分钟
2. 在输入字符串时，是否需要用引号括起来？
1. 当输入时间日期类型函数后的入参时，不需要用引号
1. 例如： `截止日期 < EndOfYear(+3M)`
2. 当筛选文本类型属性时，需要使用引号，单引号、双引号均可
1. 例如： `标题 ~ "项目管理"`