数据筛选器
为了满足复杂的数据查询需求,伙伴云对查询数据的条件提炼出「筛选器」对象的概念。在伙伴云的接口中,「筛选器」对象被广泛地使用,包括数据查询、权限设定、关联数据等场景。
筛选器示例
{
"and": [
{
"field": "subject",
"query": {
"eq": "测试"
}
},
{
"or": [
{
"field": "category",
"query": {
"in": [1, 2, 3]
}
},
{
"field": "status",
"query": {
"em": true
}
}
]
}
]
}
筛选器数据结构
筛选器的数据结构是由多个「筛选项」按照「筛选逻辑」组合而成。
筛选项
对一个字段(field)的一个查询条件(query),叫做一个「筛选项」,一个简单的「筛选项」示例如下:
{
"field": "name",
"query": {
"eq": "匹配的字符"
}
}
参数 | 类型 | 说明 |
---|---|---|
field | String | 字段 ID 或别名,可以是表格普通字段也可以是数据的系统字段(如创建时间等) |
query | Object | 筛选的查询条件,不同字段的条件结构不同,详见下文说明 |
筛选逻辑
筛选器可以通过「筛选逻辑」对象组合出满足各种场景的查询条件,一个简单的带「筛选逻辑」的筛选器如下所示:
{
"and": [
{
"field": "subject",
"query": {
"eq": "测试"
}
},
{
"field": "category",
"query": {
"in": [1, 2, 3]
}
}
]
}
目前「筛选逻辑」支持的逻辑关键字包括:and 和 or,关键字是由「筛选项」或「筛选逻辑」组成的集合,每个集合组合出的条件逻辑遵循关键字表达逻辑。
假设我们有以下的查询条件:
A AND (B OR C)
转换为筛选器后的数据结构如下:
{
"and": [
A,
{
"or": [
B,
C
]
}
]
}
Query 语法
表格中不同类型的字段所能使用的「筛选项」中的查询条件( query )是不同的。
关联字段/数据 ID 字段(item_id)
关键字 | 示例 | 示例说明 |
---|---|---|
eq | "eq": ["2000"] | 匹配 item_id = 2000 的数据 |
ne | "ne": ["2000"] | 匹配 item_id != 2000 的数据 |
in | "in": ["2000", "2001"] | 匹配 item_id = 2000 或 item_id = 2001 的数据 |
nin | "nin": ["2000", "2001"] | 匹配 item_id != 2000 且 item_id != 2001 的数据 |
em | "em": true | 匹配值为空的数据(数据 ID 无效) |
用户字段/签名字段/创建人(created_by)/修改人(updated_by)
关键字 | 示例 | 示例说明 |
---|---|---|
eq | "eq": ["1000"] | 匹配 user_id = 1000 的数据 |
ne | "ne": ["1000"] | 匹配 user_id = 1000 的数据 |
in | "in": ["1000", "1001"] | 匹配 user_id = 1000 或 ID = 1001 的数据 |
nin | "nin": ["1000", "1001"] | 匹配 user_id != 1000 且 ID != 1001 的数据 |
inc | "inc": ["1000", "1001"] | 匹配多个 user_id 是 ["1000", "1001"] 子集的数据 |
em | "em": true | 匹配值为空的数据(创建人/修改人无效) |
日期字段/计算字段(返回日期类型)/创建时间(created_on)/修改时间(updated_on)
关键字 | 示例 | 示例说明 |
---|---|---|
eq | "eq": "2021-05-11" | 匹配等于2021年05月11日的数据 |
ne | "ne": "2021-05-11" | 匹配不等于2021年05月11日的数据 |
gt | "gt": "2021-05-11" | 匹配大于2021年05月11日的数据 |
gte | "gte": "2021-05-11" | 匹配大于等于2021年05月11日的数据 |
lt | "lt": "2021-05-11" | 匹配小于2021年05月11日的数据 |
lte | "lte": "2021-05-11" | 匹配小于等于2021年05月11日的数据 |
em | "em" : true | 匹配值为空的数据(创建时间/修改时间无效) |
时间字段支持动态日期范围标记
动态日期范围标记 | 说明 |
---|---|
today | 今天 |
yesterday | 昨天 |
tomorrow | 明天 |
last_week | 过去7天(不含今天) |
last_month | 过去30天(不含今天) |
next_week | 未来7天(不含今天) |
next_month | 未来30天(不含今天) |
this_whole_week | 本周 |
last_whole_week | 上周 |
next_whole_week | 下周 |
this_whole_month | 本月 |
last_whole_month | 上月 |
next_whole_month | 下月 |
this_quarter | 本季度 |
last_quarter | 上季度 |
next_quarter | 下季度 |
this_year | 今年 |
last_year | 去年 |
next_year | 明年 |
文本字段/位置字段
关键字 | 示例 | 示例说明 |
---|---|---|
eqm | "eqm": ["匹配的文本1", "匹配的文本2"] | 匹配等于“匹配的文本1”或等于“匹配的文本2”的数据 |
eq | "eq": "匹配的文本" | 匹配等于“匹配的文本”的数据 |
ne | "ne": "匹配的文本" | 匹配不等于“匹配的文本”的数据 |
in | "in": ["匹配的文本1", "匹配的文本2"] | 匹配包含“匹配的文本1”或“匹配的文本2”的文本的数据 |
nin | "nin": ["匹配的文本1", "匹配的文本2"] | 匹配不包含“匹配的文本1”和“匹配的文本2”的文本的数据 |
ain | "ain": ["匹配的文本1", "匹配的文本2"] | 匹配包含“匹配的文本1”和“匹配的文本2”的文本的数据 |
em | "em": true | 匹配值为空的数据 |
数字字段/计算字段(返回数字类型)
关键字 | 示例 | 示例说明 |
---|---|---|
eq | "eq": 20 | 匹配等于 20 的数据 |
ne | "ne": 20 | 匹配不等于 20 的数据 |
gt | "gt": 20 | 匹配大于 20 的数据 |
gte | "gte": 20 | 匹配大于等于 20 的数据 |
lt | "lt": 20 | 匹配小于 20 的数据 |
lte | "lte": 20 | 匹配小于等于 20 的数据 |
em | "em": true | 匹配值为空的数据 |
选项字段
关键字 | 示例 | 示例说明 |
---|---|---|
eq | "eq": ["1"] | 匹配 备选项ID = 1 的数据 |
ne | "ne": ["1"] | 匹配 备选项ID != 1 的数据 |
in | "in": ["1", "2"] | 匹配 备选项ID = 1 或 备选项ID = 2 的数据 |
nin | "nin": ["1", "2"] | 匹配 备选项ID != 1 且 备选项ID != 2 的数据 |
em | "em": true | 匹配值为空的数据 |
图片字段/附件字段
关键字 | 示例 | 示例说明 |
---|---|---|
em | "em": true | 匹配值为空的数据 |
最后修改时间: 2 年前