ObjectSet 聚合
更新时间：2026-09-24
接口描述
对 ObjectSet 进行分组聚合统计，支持多种聚合类型与分组方式。
权限说明
需具备对应工作空间及本体（ontology）的数据查看权限。
注意事项
- workspaceId、ontology 不存在或无权限时，请求会失败。
- limit 限制返回条数，最大 10,000。
请求结构
Plain Text
1POST /v1/workspaces/{workspaceId}/ontologies/{ontology}/objectSets/aggregate HTTP/1.1
2Host: databuilder.bd.baidubce.com
3Authorization: authorization string
4
5{
6 "objectSet": { "type": "base", "objectType": "Order" },
7 "aggregation": [ { "type": "sum", "field": "amount", "name": "total_amount" } ],
8 "groupBy": [ { "type": "exact", "field": "region" } ],
9 "limit": 100
10}请求头域
除公共头域（含 Authorization 鉴权）外，无其它特殊头域。
请求参数
Path 参数
| 参数名 | 类型 | 是否必须 | 含义 |
|---|---|---|---|
| workspaceId | String | 是 | 工作空间 ID |
| ontology | String | 是 | 本体名称 |
Body 参数（application/json）
聚合查询请求体。
| 参数名 | 类型 | 是否必须 | 含义 |
|---|---|---|---|
| objectSet | Object | 是 | ObjectSet 定义，支持递归嵌套结构，见下 |
| aggregation | Array<Object> | 是 | 聚合函数列表，见下 |
| groupBy | Array<Object> | 否 | 分组条件列表，见下 |
| having | Object | 否 | 聚合结果过滤（对应 SQL HAVING），支持 and/or 组合及 eq/ne/gt/ge/lt/le/in/not_in，见下 |
| orderBy | Object | 否 | 排序配置，支持聚合别名和 GROUP BY 字段混合排序，见下 |
| limit | integer | 否 | 最多返回条数，不传默认 10000，范围 [1, 10000] |
objectSet 定义
| 参数名 | 类型 | 是否必须 | 含义 |
|---|---|---|---|
| type | String | 是 | ObjectSet 类型：base、filter、searchAround、intersect、union、subtract、parameter。注意：parameter 类型仅 ActionType 内部使用，直接调用不应使用此类型 |
| objectType | String | 否 | 当 type = base 时指定 objectType 名称；当 type = searchAround 时指定目标 objectType 名称 |
| parameterId | String | 否 | 当 type = parameter 时指定参数 ID（仅供 ActionType 内部使用） |
| objectSet | Object | 否 | 当 type = filter 或 searchAround 时，指定嵌套的 objectSet |
| where | Object | 否 | 当 type = filter 时，指定过滤条件，见下 |
| link | String | 否 | 当 type = searchAround 时，指定关联的 link 名称（需同时指定 objectType） |
| objectSets | Array | 否 | 当 type = intersect、union、subtract 时，指定多个 objectSet |
where 定义
| 参数名 | 类型 | 是否必须 | 含义 |
|---|---|---|---|
| type | String | 否 | 条件类型，支持的运算符见下表 |
| field | String | 否 | 叶子条件使用，属性名 |
| value | - | 否 | 叶子条件使用，属性值；类型根据条件类型而定：比较类为字符串/数值，in/not_in 为数组，contains 为向量数组 |
| filter | Array<Object> | 否 | 组合条件（and/or/not）使用，元素结构同 where |
where.type 支持的运算符：
| 类别 | 运算符 |
|---|---|
| 比较类 | eq(等于)、ne(不等于)、lt(小于)、le/lte(小于等于)、gt(大于)、ge/gte(大于等于) |
| 集合类 | in(包含于)、not_in(不包含于) |
| 字符串类 | like(模糊匹配)、not_like(不匹配)、starts_with(前缀匹配)、ends_with(后缀匹配) |
| 空值类 | is_null(为空)、is_not_null(非空) |
| 向量类 | contains(向量搜索)、match_any、match_all、match_phrase、match_phrase_prefix、match_regexp |
| 逻辑类 | and、or、not |
aggregation 元素
| 参数名 | 类型 | 是否必须 | 含义 |
|---|---|---|---|
| type | String | 是 | 聚合类型：count、min、max、avg、sum、exactDistinct、percentileApprox、variance、stddev |
| field | String | 否 | 聚合字段（count 类型可省略，等价 COUNT(*)） |
| name | String | 否 | 聚合结果别名，支持中文/英文/数字/下划线 |
| percentile | number | 否 | 仅 type=percentileApprox 时使用，百分位值范围 (0, 1] |
groupBy 元素
| 参数名 | 类型 | 是否必须 | 含义 |
|---|---|---|---|
| type | String | 是 | 分组类型：exact、range、fixedWidth、duration |
| field | String | 是 | 分组字段名 |
| ranges | Array<Object> | 否 | type=range 时使用，范围列表，见下 |
| fixedWidth | integer | 否 | type=fixedWidth 时使用，分桶宽度 |
| value | integer | 否 | type=duration 时使用，时间间隔值 |
| unit | String | 否 | type=duration 时使用，时间单位：YEARS、QUARTERS、MONTHS、WEEKS、DAYS、HOURS、MINUTES、SECONDS |
groupBy.ranges 元素
| 参数名 | 类型 | 是否必须 | 含义 |
|---|---|---|---|
| startValue | String | 否 | 范围起始值（不含本值则为开区间） |
| endValue | String | 否 | 范围结束值（不含本值则为开区间） |
having 定义
| 参数名 | 类型 | 是否必须 | 含义 |
|---|---|---|---|
| type | String | 是 | 条件类型：叶子条件 eq、ne、gt、ge、lt、le、in、not_in；组合条件 and、or |
| field | String | 否 | 字段名（聚合别名或 GROUP BY 字段），叶子条件必填，and/or 组合条件不需要 |
| value | - | 否 | 叶子条件使用，属性值 |
| filter | Array<Object> | 否 | and/or 组合条件使用，子条件列表，叶子条件不需要 |
orderBy 定义
| 参数名 | 类型 | 是否必须 | 含义 |
|---|---|---|---|
| fields | Array<Object> | 否 | 排序字段列表，见下 |
orderBy.fields 元素
| 参数名 | 类型 | 是否必须 | 含义 |
|---|---|---|---|
| field | String | 是 | 排序字段名（聚合别名或 GROUP BY 字段） |
| direction | String | 否 | 排序方向：asc 或 desc，默认 asc |
响应头域
除公共头域外，无其它特殊头域。
响应参数
| 参数名 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| requestId | String | 是 | 请求 ID |
| code | String | 是 | 业务响应状态码 |
| message | String | 否 | 失败时返回错误信息 |
| result | Object | 是 | 响应结果主体，见下 |
result
| 参数名 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| data | Array<Object> | 否 | 聚合结果数据，元素见下 |
| nextMarker | String | 否 | 下一页 marker，为 null 时表示已到最后一页 |
| sql | String | 否 | 本次执行的 SQL 语句（调试用，仅特定配置下返回），用户侧不要使用 |
| pageSize | Integer | 否 | 本次查询的每页大小 |
| total | Integer | 否 | 满足条件的记录总数；withTotal=true 时返回实际总数，否则为 null |
错误码
通用错误码可参考如下（本体接口专属错误码待确认，以最新实现为准）：
| 错误码 | 错误描述 | HTTP 状态码 | 中文解释 |
|---|---|---|---|
| AccessDenied | 无操作权限 | 403 | 暂无操作权限 |
| IllegalArgument | 参数非法 | 400 | 用户提供参数错误 |
请求示例
Plain Text
1{
2 "objectSet": {
3 "type": "base",
4 "objectType": "string",
5 "parameterId": "string",
6 "objectSet": {},
7 "where": {
8 "type": "string",
9 "field": "string",
10 "value": {},
11 "filter": [
12 {
13 "type": "string",
14 "field": "string",
15 "value": {},
16 "filter": [
17 {}
18 ]
19 }
20 ]
21 },
22 "link": "string",
23 "objectSets": [
24 {}
25 ]
26 },
27 "aggregation": [
28 {
29 "type": "string",
30 "field": "string",
31 "name": "string",
32 "percentile": 0
33 }
34 ],
35 "groupBy": [
36 {
37 "type": "string",
38 "field": "string",
39 "ranges": [
40 {
41 "startValue": "string",
42 "endValue": "string"
43 }
44 ],
45 "fixedWidth": 0,
46 "value": 0,
47 "unit": "string"
48 }
49 ],
50 "having": {
51 "type": "string",
52 "field": "string",
53 "value": {},
54 "filter": [
55 {}
56 ]
57 },
58 "orderBy": {
59 "fields": [
60 {
61 "field": "string",
62 "direction": "string"
63 }
64 ]
65 },
66 "limit": 0
67}响应示例
JSON
1{
2 "requestId": "string",
3 "code": "string",
4 "message": "string",
5 "result": {
6 "data": [
7 {
8 "group": {},
9 "metrics": [
10 {
11 "name": "string",
12 "value": {}
13 }
14 ]
15 }
16 ]
17 }
18}评价此篇文章