查询接口的参数

引言

平台提供了非常丰富强大的数据查询能力，你可以通过查询参数，获取预期的响应数据。本文将会详细介绍每一个

danger

• GET /object 列表查询
• GET /object/:id 单ID查询

访问接口请不要添加随机参数，会影响前置缓存命中率，降低接口性能。

分页

适用接口: 列表

GET { prefix }/object?page=2&size=50

◎ page 请求页数，默认 1

◎ size 分页大小，默认 20

• 场景 1：没有传page参数，size不会生效
• 场景 2：size=total 时拉取全量数据，但不能传page参数(底层限制了最大只能拉取15000条，如果超出请自行翻页！)

字段筛选

适用接口: 列表、单ID

GET { prefix }/object?exclude=key1,key2

◎ exclude 只排除字段，与include互斥

◎ include 只包含字段，与exclude互斥，优先exclude

排序

适用接口: 列表

GET { prefix }/object?sort=score&order=desc

◎ sort 排序字段，默认 _ctime

◎ order 排序方式(正序: asc, 倒序: desc)，默认 asc，例子：

{
  sort: 'key1,key2,key3',
  order: 'asc'
}
// 混合顺序
{
  sort: 'key1,key2,key3',
  order: 'asc,desc,asc'
}

◎ ignore_order 是否忽略平台默认排序。若要忽略，请使用 ignore_order=1

平台默认排序

在查询时不指定 sort 和 order 字段时，平台默认使用 _ctime 字段进行排序。

数据过滤

适用接口: 列表

GET { prefix }/object?filter=encodeURIComponent('field1="abc"&score>1') 最终实际输出为：filter=field1%3D%22abc%22%26score%3E1

重要提示：

1. 注意encodeURIComponent的用法。 encodeURIComponent的作用是防止filter参数里面有类似&/=之类参数，影响正常URL解析。以上示例，请求时的URL应为:

/path-to-api/object?filter=field1%3D%22abc%22%26score%3E1

2. 筛选值必须严格按照对应类型，如果字段数据是字符串，那么查询的参数必须为:

filter=encodeURIComponent('strName="xxx-string"')
# output
filter=strName%3D%22xxx-string%22

3. 筛选值不能留空，否则会报语法错误

# bad
filter=encodeURIComponent('foo=&bar="1"')

# good
filter=encodeURIComponent('foo=""&bar="1"')

◎ filter 数据查询过滤，例如："field1="abc"&score>1"。已支持的过滤操作：

• 基本匹配
  • 等于(=)
  • 不等于(!=)
  • 大于(>)
  • 大于等于(>=)
  • 小于(<)
  • 小于等于(<=)
• 模糊匹配
  • 字符串模糊匹配(%%)
  • 字符串开头等于(=%)
  • 字符串结尾等于(%=)
  • 字符串不包含(!%)
• 内嵌对象
  • 包含其中某项(=["abc","efg"])　　　　 　例如：值为["abc","123"]则匹配，值为["hij", "456"]则过滤
  • 都不包含其中某项(!=["abc","efg"])　　　例如：值为["456","hij"]则匹配，值为["123", "efg"]则过滤
  • 此语法亦适用于字符串字段，例如规则 =["gh"] 可匹配字符串值 abc,def,gh（项之间用逗号分隔）
• 关系运算
  • 支持 & | 以及 圆括号
  • 或运算优先级最低，例子：field1="abc" & score>1 | field2="efg" & score<=2 相当于 (field1="abc"&score>1) | (field2="efg"&score<=2)
• 筛选值：
  • Number => score>1
  • Bloolean => isChecked=true
  • String => name="abc"
  • Object => map={"key":1}
  • Array => list=[1,2,3]
  • null => empty=null
  • undefined => undef=undefined
• 空值与非空值： 针对字符串值类型字段，允许使用空值与非空值过滤。注意此处操作匹配符为 == 或 !=

  - `空值` => **name==''|name==null** 
  - `非空值` => **name!=''&name!=null** 
  
  

计数

适用接口: 列表

GET { prefix }/object?count=1

◎ count 只返回总条数

{ total: 1 }

注意: 字段筛选，排序对计数查询无效，可以与分页，数据过滤结合来用

关联

适用接口: 列表、单ID

GET { prefix }/object?link=1&link_query=encodeURIComponent('include=name')

GET { prefix }/object?link=fieldA,fieldB&link_query=encodeURIComponent('{"fieldA":"include=name","fieldB":"include=age"}')

◎ link 关联查询

• 取布尔值 link=1：拉取当前表所有的关联字段

◎ link_fields 关联查询字段

• 只有在 link=1时生效
• 取数组 link_fields=fieldA,fieldB: 只拉取 fieldA 和 fieldB 的关联值

◎ link_query 关联查询筛选参数

• 取值字符串 link_query=encodeURIComponent('include=name'): 所有关联对象按照此query查询
• 取值JSON字符串 link_query=encodeURIComponent('{"fieldA":"include=name","fieldB":"include=age"}'): 按照字段设置不同的关联查询参数
  • 注意: 如果使用索引（非主键）关联，且 link_query 中指定了 include，则必须包含此索引字段。

◎ link_depth 关联查询深度层级：取值数字整型，默认只关联一级

◎ link_skip 关联失败是否跳过：取值布尔值 1/0，默认为 0(false)

• link_skip=0 A 表的 fieldA 字段主键关联到B表，fieldA 的值为["foo","bar"] ，如果B表中没有id="foo"的数据，则查询返回 fieldA=[null, id="bar"的数据] 保证关联顺序。
• 若开启了表版本，需要在修改关联表配置后发一次版，高性能接口才会生效。

左连接（Left Join）

适用接口: 列表、单ID

GET { prefix }/object?join=alias_name

◎ join 需要执行的左连接的名称，使用左连接前需要在主表进行配置，配置方法如下图

注意

• 只支持join一个表，即 join=name1
• 针对高性能接口，若表开启了表版本管理，需要在修改关联表配置后发一次版，高性能接口才会生效。

提示: join参数可以和filter等其他查询参数共同使用，支持对子表进行filter，比如/api/object?join=name1&filter=encodeURIComponent('name1.id="id1"')

BUG: join目前包含一对一和一对多两种模式，其中一对一模式下若发现重复数据会自动去重，但是count时无法自动去重，因此若在一对一模式下使用count参数，请务必保证真实数据是一对一的，否则会导致count数量比实际数量多。（多出重复的那部分数据)

分组（Group By）

适用接口: 列表、单ID

GET { prefix }/object?group=field_name&ignore_case=1

◎ group 需要执行group by的字段名，多个字段以逗号连接。进行 group 的字段必须是索引字段，否则平台会报错。

◎ ignore_case 分组的时候是否需要区分大小写。默认不区分大小写。若要区分，请传ignore_case=0

时间输出格式

适用接口: 列表、单ID

GET { prefix }/object?datetime=timestamp

◎ datetime 设置时间字段的返回格式，可取值如下：

• iso（默认）返回ISO时间字符串，时区为0时区，例子："2019-07-15T11:04:37.989Z"
• datetime 返回北京时间字符串，例子："2019-07-15 19:04:37.989"
• timestamp 返回 Unix 时间戳（毫秒）：1563188677989
• second 返回 Unix 时间戳（秒）：1563188677

布尔值输出格式

适用接口列表、单ID :

GET { prefix }/object?bool_type=number

◎ bool_type 设置时间字段的返回格式，可取值如下：

• （默认）按照DB类型返回。MySQL返回 0 / 1，MongoDB返回 true / false。
• number 固定返回 0 / 1
• boolean 固定返回 true / false