# ONESQL筛选
URL: https://docs.ones.cn/on-premises/7.33/product-manual/ones-project/issues/onesql-filter
## 1 介绍
ONESQL用于构建结构化的查询来筛选工作项，它允许用户通过 **类似SQL的语句** 配置筛选条件，以更灵活地获取目标工作项数据。相比基础筛选器，ONESQL 可以表达更复杂的条件逻辑，能够帮助研发团队提升信息检索效率，支持 **更精细、更复杂的业务数据查询场景** 。
## 2 功能入口
在特定产品模块的工作项视图内，可以点击「筛选」按钮，切换 到 **「ONESQL」tab** ，在ONESQL编辑器内输入语句、进行工作项查询。
**具体支持ONESQL筛选方式的模块如下：**
- 我的工作台
- 筛选器
- 临时筛选器
- 项目管理-「筛选器」组件
- 项目管理-「工作项类型」组件
- 项目管理-「迭代」组件
- 未规划工作项筛选器
- 所有工作项筛选器
- 工作项类型筛选器
- 筛选器
- 工作项详情页
- 关联工作项弹窗
- 规划发布内容弹窗
请注意，其他模块的视图暂时不支持ONESQL筛选方式。
## 3 语法介绍
### 3.1 认识ONESQL语法
ONESQL 查询语句通常由 **属性字段、运算符、值或函数** 组成，多个语句之间可以通过关键词组合，构建复杂条件。
- **属性字段（Field）**
工作项的系统字段或自定义字段，例如「标题」、「状态」、「负责人」、「截止日期」。
- **运算符（Operator）**
用于比较字段与条件，例如 `=` 、 `!=` 、 `>` 、 `<` 、 `IN` 、 `IS` 等。
运算符是连接属性和值的桥梁，确保查询结果符合预期条件。
- **关键词（Keyword）**
用于逻辑组合和控制，例如 `AND` 、 `OR` 、 `NOT` 。
通过关键词可以拼接多个查询语句，构建复杂的逻辑关系。
- **函数（Function）**
表现为函数名加括号，例如 `now()` 、 `currentUser()` 、 `DepartmentOf()` 。
函数用于动态计算或引用特定对象（如时间、用户、部门），增强语句灵活性。
例如，现在有这样一个查询：
这个查询语句对应的语法元素如下：
这个查询语句的含义是，查找「负责人」不是当前用户、且「状态」不包含「已关闭」的工作项。
让我们再看一些实际例子：
```text
所属项目 == 研发管理
```
此查询查找「所属项目」为「研发管理」的工作项，查询语句中包含属性「所属项目」、运算符 `==` 和值 `研发管理` 。
```text
所属项目 != 研发管理 AND 负责人 == currentUser()
```
此查询查找「所属项目」不是「研发管理」、且「负责人」是当前用户的工作项，查询语句使用了属性「所属项目」、「负责人」，运算符 `!=` 、 `==` 、关键词 `AND` 和函数 `currentUser()` 。
### 3.2 运算符
运算符是 ONESQL 中用于 **建立属性与条件之间比较关系** 的符号，例如 `=、!=、>、IN、IS`
#### 运算符说明
ONESQL 支持以下运算符：
| 运算符类型 | 运算符 | 运算符说明 | 实际举例 |
| 比较运算符 | < | 小于：
- X1- X1：数字/日期/时间类型的属性 | 查找截止日期早于 2008-12-31上午9:00 的工作项
`截止日期 < "2008/12/31 09:00"` |
| <= | 小于等于：
- X1<=X2
- X1：数字/日期/时间类型的属性 | 查找截止日期不晚于 2008-12-31上午9:00 的工作项
`截止日期 <= "2008/12/31 09:00"` |
| > | 大于：
- X1>X2
- X1：数字/日期/时间类型的属性 | 查找截止日期晚于 2008-12-31上午9:00 的工作项
`截止日期 > "2008/12/31 09:00"` |
| >= | 大于等于：
- X1>=X2
- X1：数字/日期/时间类型的属性 | 查找截止日期不早于 2008-12-31上午9:00 的工作项
`截止日期 >= "2008/12/31 09:00"` |
| == | 等于：
- X1 == X2
- X1：数字/日期/时间/选择/工作项/成员/文本类型的属性
- 该运算符后，仅支持输入单个值 | 查找截止日期是 2008-12-31上午9:00 的工作项
`截止日期 == "2008/12/31 09:00"` |
| != | 不等于：比较
- X1 != X2
- X1：数字/日期/时间/选择/工作项/成员/文本类型的属性
- 该运算符后，仅支持输入单个值 | 查找截止日期不是 2008-12-31上午9:00 的工作项
`截止日期 != "2008/12/31 09:00"` |
| 集合运算符 | IN | 包含
- X IN (X1, X2 , X3, …… Xn)
- X：数字/日期/时间/选择/工作项/成员类型的属性 | 查找优先级为P0或者P1的工作项：
`优先级 in (P0, P1)` |
| NOT IN | 不包含
- X NOT IN (X1, X2 , X3, …… Xn)
- X：数字/日期/时间/选择/工作项/成员类型的属性 | 查找优先级不是P0也不是P1的工作项：
`优先级 not in (P0, P1)` |
| 空值判断运算符 | IS | 是
- X is EMPTY
- X: 数字/日期/时间/选择/工作项/成员/文件/文本的属性 | 查找没有关联发布的工作项
`关联发布 is empty` |
| IS NOT | 不是
- X is not EMPTY
- X: 数字/日期/时间/选择/工作项/成员/文件/文本的属性 | 查找有所属迭代的工作项
`所属迭代 is not empty` |
| 字符串匹配运算符 | ~ | 包含
- X ~ "X1"
- X：文本类型的属性 | 查找标题里包含"小蓝"的工作项
`标题 ~ "小蓝"` |
| !~ | 不包含
- X !~ "X1"
- X：文本类型的属性 | 查找标题里不包含"小蓝"的工作项
`标题 !~ "小蓝"` |
在ONESQL编辑器中，输入属性后，语法补全卡片会主动展示该属性支持的运算符。若需要进一步了解具体运算符用法，可以悬停在该运算符选项上，查看详细说明。
#### 运算符优先级规则
在复杂的 ONESQL 语句中，可以通过括号来控制运算符的优先级：
- **有括号时** ：括号内的条件优先计算。
- **无括号时** ： `AND` 的优先级高于 `OR` ，语句将从左到右依次计算。
**示例：**
```text
(状态 == 已完成 AND 所属项目 == SysAdmin) OR 负责人 == 张三
```
此语句会先查找 **SysAdmin 项目中所有已完成的工作项** ，再将结果与 **负责人是张三的工作项** 合并。
建议在复杂语句中始终使用括号，避免逻辑歧义。
### 3.3 函数
针对业务中高频的筛选场景，ONESQL提供了已封装好筛选逻辑的函数，每个函数都有特定的功能，比如 `DepartmentOf()` 用来引用和查找部门， `EndOfDay()` 用来获取时间等。
ONESQL提供的函数如下：
| 使用场景 | 函数 | 入参说明 | 使用方法 | 示例 |
| 筛选 **时间日期类型** 的属性 | now(X) | X： 字符串，支持 `(+/-)nn(y\|M\|w\|d\|h\|m)`
- `+` / `-` ：正负偏移，若省略则默认为 `+`
- `nn` ：整数
- 单位：
- y：年
- M：月
- w：周
- d：天（默认单位）
- h：小时
- m：分钟 | 获取当前时间 | 创建时间晚于昨天的工作项：
`创建时间 > now(-1d)` |
| StartOfDay(X) | X： 修饰字符串， `(+/-)nn(y\|M\|w\|d\|h\|m)`
- `+` / `-` ：正负偏移，若省略则默认为 `+`
- `nn` ：整数
- 单位：
- y：年
- M：月
- w：周
- d：天（默认单位）
- h：小时
- m：分钟 | 计算当天开始的时间（当天00:00:00）增加X1（当X1为正）或减少X1（当X1为负）后的时间 | 查找过去三天内创建的工作项
`创建日期 > StartOfDay(-3d)` |
| StartOfWeek(X) | X： 修饰字符串，(+/-)nn(y\|M\|w\|d\|h\|m)
- `+` / `-` ：正负偏移，若省略则默认为 `+`
- `nn` ：整数
- 单位：
- y：年
- M：月
- w：周（默认单位）
- d：天
- h：小时
- m：分钟 | 计算本周开始的时间（开始日的00:00:00）增加X1（当X1为正）或减少X1（当X1为负）后的时间 | 查找上周内创建的工作项
`创建日期 > StartOfWeek(-1) AND 创建日期 < StartOfWeek()` |
| StartOfMonth(X) | X： 修饰字符串，(+/-)nn(y\|M\|w\|d\|h\|m)
- `+` / `-` ：正负偏移，若省略则默认为 `+`
- `nn` ：整数
- 单位：
- y：年
- M：月（默认单位）
- w：周
- d：天
- h：小时
- m：分钟 | 计算本月开始的时间（本月一号的00:00:00）增加X1（当X1为正）或减少X1（当X1为负）后的时间 | 查找上月以来创建的工作项
`创建日期 > StartOfMonth(-1)` |
| StartOfYear(X) | X： 修饰字符串，(+/-)nn(y\|M\|w\|d\|h\|m)
- `+` / `-` ：正负偏移，若省略则默认为 `+`
- `nn` ：整数
- 单位：
- y：年（默认单位）
- M：月
- w：周
- d：天
- h：小时
- m：分钟 | 计算今年开始的时间（今年1月1号的00:00:00）增加X1（当X1为正）或减少X1（当X1为负）后的时间 | 查找今年以来创建的工作项
`创建日期 > StartOfYear` |
| EndOfDay(X) | X： 修饰字符串，(+/-)nn(y\|M\|w\|d\|h\|m)
- `+` / `-` ：正负偏移，若省略则默认为 `+`
- `nn` ：整数
- 单位：
- y：年
- M：月
- w：周
- d：天（默认单位）
- h：小时
- m：分钟 | 计算当天结束的时间（当天23:59:59）增加X1（当X1为正）或减少X1（当X1为负）后的时间 | 查找明天结束前截止的工作项目：
`截止日期 < EndOfDay(+1)` |
| EndOfWeek(X) | X： 修饰字符串，(+/-)nn(y\|M\|w\|d\|h\|m)
- `+` / `-` ：正负偏移，若省略则默认为 `+`
- `nn` ：整数
- 单位：
- y：年
- M：月
- w：周（默认单位）
- d：天
- h：小时
- m：分钟 | 计算本周结束的时间（本周结束日的23:59:59）增加X1（当X1为正）或减少X1（当X1为负）后的时间 | 查找下周末截止的工作项目
`截止日期 < EndOfWeek(+1)` |
| EndOfMonth(X) | X： 修饰字符串，(+/-)nn(y\|M\|w\|d\|h\|m)
- `+` / `-` ：正负偏移，若省略则默认为 `+`
- `nn` ：整数
- 单位：
- y：年
- M：月（默认单位）
- w：周
- d：天
- h：小时
- m：分钟 | 计算本月结束的时间（月末那天的23:59:59）增加X1（当X1为正）或减少X1（当X1为负）后的时间 | 查找下个月 15 号之前截止的工作项
`截止日期 < EndOfMonth(+15d)` |
| EndOfYear(X) | X： 修饰字符串，(+/-)nn(y\|M\|w\|d\|h\|m)
- `+` / `-` ：正负偏移，若省略则默认为 `+`
- `nn` ：整数
- 单位：
- y：年（默认单位）
- M：月
- w：周
- d：天
- h：小时
- m：分钟 | - 计算今年结束的时间（今年12月31日的23:59:59）增加X1（当X1为正）或减少X1（当X1为负）后的时间 | 查找明年三月底前截止的工作项
`截止日期 < EndOfYear(+3M)` |
| 筛选 **成员类型** 的属性 | DepartmentOf(X) | X是部门的名称，支持输入多个部门 | 获取特定部门内的成员 | 查找产品部门、研发部门成员负责的工作项
`负责人 in DepartmentOf(产品部门，研发部门)` |
| GroupOf(X) | X是用户组的名称，支持输入多个用户组 | - 获取特定用户组内的成员 | 查找测试用户组里成员负责的工作项
`负责人 in GroupOf(测试)` |
| RolesOf(X) | X是角色的名称，支持输入多个角色 | - 获取特定角色包含的成员 | 查找CDT小组成员负责的工作项
`负责人 in RolesOf(CDT小组)` |
| currentUser() | 无入参 | 获取当前用户 | 查找分配给自己的工作项
`负责人 = currentUser()` |
| 筛选 **单选级联** 属性 **、多选级联** 属性 **、所属模块** 属性 | expand(X) | X是节点属性值，支持输入多个属性值 | - 查找属性某个节点及该节点下的所有子节点 | 查询级联属性"位置"的值包含"江苏省"、"浙江省"的工作项
`位置 in (江苏省, 浙江省)`
包含江苏省、浙江省下的所有节点选项值
`位置 in expand(江苏省, 浙江省)` |
和运算符一样，在编辑ONESQL语句时，可以通过自动补全卡片查看函数的具体用法。当输入属性、运算符后，自动补全卡片会展示当前属性支持使用的函数。
### 3.4 关键词
目前ONESQL语法支持的逻辑关键字包括：
- `AND` ：且
- `OR` ：或
- `NOT` ：非
- `EMPTY` ：为空
## 4 使用ONESQL筛选
### 4.1 场景示例
ONESQL筛选的操作都在编辑器内完成，以下场景列举了常见的筛选诉求对应的ONESQL语句，实际属性因业务场景而异，但是查询语句的整体逻辑和结构不变。
- **场景一：找出分配给自己的未完成任务**
```text
负责人 == currentUser() AND 状态类型 != 已完成
```
- **场景二：查询上周内创建的缺陷**
```text
工作项类型 == 缺陷 AND 创建时间 > StartOfWeek(-1) AND 创建时间 < StartOfWeek()
```
- **场景三：筛选产品部成员负责的需求**
```text
工作项类型 == 需求 AND 负责人 in DepartmentOf(产品部)
```
- **场景四：查找即将在下月15日前到期的任务**
```text
截止日期 < EndOfMonth(+15d)
```
### 4.2 基础筛选和ONESQL切换
对于已经配置了筛选条件的基础筛选器，可以带条件一键切换到ONESQL模式下，并在ONESQL编辑器内继续维护筛选条件。
点 击 **「应用基础筛选条件」** ，即可复制当前视图的基础筛选条件，并自动填充到编辑器内
填充后效果如下，用户可以继续编辑语句、完成视图筛选。
## 5 常见问题
1. ONESQL语法中的英文区分大小写吗？
- ONESQL 语法中的逻辑关键词、运算符、函数均 **不区分英文大小写**
1. 我写好了ONESQL语句，但是提示有错误，如何看到ONESQL语句 **错在哪里** ？
- ONESQL报错信息会在 **行内和编辑器底部** 展示。
- 查看行内的错误信息时，需要鼠标悬停在错误处
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` ，代表时间长度是一天两小时三分钟
1. 在输入字符串时，是否需要用引号括起来？
1. 当输入 **时间日期类型函数后的入参** 时，不需要用引号
1. 例如： `截止日期 < EndOfYear(+3M)`
2. 当筛选 **文本类型属性** 时，需要使用引号，单引号、双引号均可
1. 例如： `标题 ~ "项目管理"`