业务指标

资源说明

业务指标的定义

数据工程师面对分析师的需求，需要将业务数据库的数据集、字段整理创建成业务指标，供分析师以业务指标为基本单位进行数据下载和分析。

业务指标结构说明

Metric

下面是业务指标特有的结构说明

字段	类型	描述
createdBy	LONG	创建者的userId
createdAt	DATE	创建时间
updatedBy	LONG	更新者的userId
updatedAt	DATE	更新时间
where	HE 数组	限定条件
dimensions	JSONOBJECT 数组	定义分析维度
pathAttr	METRIC 数组	路径归因
description	STRING	业务含义
category	STRING	类别，默认值为"measure"
granularityId	LONG	粒度 ID
granularity	OBJECT	数据集粒度结构说明
extraOptions	JSONOBJECT	描述信息

MetricDto

字段	类型	描述
creator	OBJECT	创建者信息
updater	OBJECT	更新者信息
action	STRING	权限描述, admin-read-write是管理者权限，read-write是编辑者权限，read是查看者权限

接口说明

MeasureDimDto 结构（分析上下文相关）

字段	类型	说明
selectedMeasures	List<DatasetFieldDto>	已选指标（请求字段）
selectedFields	List<DatasetFieldDto>	已选维度（请求字段）
candidateMeasures	List<DatasetFieldDto>	候选指标（请求/响应字段）
needUnionFields	BOOLEAN	是否返回维度并集（请求字段，仅 true 时返回）
compatibleMeasures	List<DatasetFieldDto>	可兼容指标（响应字段）
intersectionFields	List<DatasetFieldDto>	维度交集（响应字段）
unionFields	List<DatasetFieldDto>	维度并集（响应字段，受 needUnionFields 控制）
measureSubjectId	LONG	主题域文件夹 id
measureSubjectTitle	STRING	主题域名称
appId	LONG	解析出的 appId（可选）
datasetId	LONG	解析出的 datasetId（可选）
appParams	List<AppParam>	解析出的数据包所属应用参数列表（响应字段）

新增业务指标

请求URL

http

POST /api/apps/{appId}/datasets/{datasetId}/measures HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

request body 请求体

业务指标结构说明

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
data	OBJECT	业务指标共同结构见业务指标结构说明

接口示例

RequestResponse

http

POST /api/apps/119287/datasets/7/measures HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
  "label": "988test",
  "description": "",
  "action": "write",
  "appId": 119287,
  "datasetId": 7,
  "dimensions": [
    {
      "datasetId": 7,
      "fieldName": "省/自治区",
      "label": "省/自治区"
    },
    {
      "datasetId": 7,
      "fieldName": "城市",
      "label": "城市"
    }
  ],
  "expr": {
    "kind": "formula",
    "op": "SUM({销售额})"
  },
  "pathAttr": [
  ]
}

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "msg": "success",
  "data": {
    "datasetId": 7,
    "fieldName": "c1",
    "appId": 119287,
    "tags": {
    },
    "createdBy": 11549,
    "createdAt": "2023-02-10 11:04:12",
    "updatedBy": 11549,
    "updatedAt": "2023-02-10 11:04:12",
    "dimensions": [
      {
        "fieldName": "省/自治区",
        "datasetId": 7,
        "label": "省/自治区"
      },
      {
        "fieldName": "城市",
        "datasetId": 7,
        "label": "城市"
      }
    ],
    "pathAttr": [
    ],
    "description": "",
    "category": "measure",
    "label": "988test",
    "expr": {
      "kind": "formula",
      "op": "SUM({销售额})",
      "type": "number",
      "value": "SUM({销售额})",
      "isAggregate": true,
      "isConstant": false,
      "allFieldsFromBaseDataset": true
    },
    "type": "number",
    "config": {
    }
  }
}

复制业务指标

请求URL

http

POST /api/apps/{appId}/datasets/{datasetId}/measures/{fieldName}/duplicate HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

request body 请求体

字段	类型	是否必须	说明
label	STRING	是	别名

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
data	OBJECT	业务指标共同结构见业务指标结构说明

接口示例

RequestResponse

http

POST /api/apps/119287/datasets/7/measures/c1/duplicate HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
  "label": "988test1"
}

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "msg": "success",
  "data": {
    "datasetId": 7,
    "fieldName": "c2",
    "appId": 119287,
    "tags": {
    },
    "createdBy": 11549,
    "createdAt": "2023-02-10 11:08:42",
    "updatedBy": 11549,
    "updatedAt": "2023-02-10 11:08:42",
    "dimensions": [
      {
        "fieldName": "省/自治区",
        "datasetId": 7,
        "label": "省/自治区"
      },
      {
        "fieldName": "城市",
        "datasetId": 7,
        "label": "城市"
      }
    ],
    "pathAttr": [
    ],
    "description": "",
    "category": "measure",
    "label": "988test1",
    "expr": {
      "kind": "formula",
      "op": "SUM({销售额})",
      "type": "number",
      "value": "SUM({销售额})",
      "isAggregate": true,
      "isConstant": false,
      "allFieldsFromBaseDataset": true
    },
    "type": "number",
    "config": {
    }
  }
}

更新业务指标

请求URL

http

PUT /api/apps/{appId}/datasets/{datasetId}/measures?fieldName= HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

request body 请求体

业务指标结构说明

URL 参数

字段	类型	是否必须	说明
force	BOOLEAN	否	是否强制更新数据集

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
data	OBJECT	业务指标共同结构见业务指标结构说明

接口示例

RequestResponse

http

PUT /api/apps/119287/datasets/7/measures?fieldName=c1 HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
  "datasetId": 7,
  "fieldName": "c1",
  "appId": 119287,
  "tags": {
  },
  "dimensions": [
    {
      "fieldName": "省/自治区",
      "datasetId": 7,
      "label": "省/自治区"
    },
    {
      "fieldName": "城市",
      "datasetId": 7,
      "label": "城市"
    }
  ],
  "pathAttr": [
  ],
  "description": "",
  "category": "measure",
  "label": "988test",
  "expr": {
    "kind": "formula",
    "op": "SUM({销售额})",
    "type": "number",
    "isAggregate": true,
    "isConstant": false,
    "allFieldsFromBaseDataset": true
  },
  "type": "number",
  "action": "admin|read|write||",
  "config": {
  }
}

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "msg": "success",
  "data": {
    "datasetId": 7,
    "fieldName": "c1",
    "appId": 119287,
    "tags": {
    },
    "updatedBy": 11549,
    "updatedAt": "2023-02-10 11:16:53",
    "dimensions": [
      {
        "fieldName": "省/自治区",
        "datasetId": 7,
        "label": "省/自治区"
      },
      {
        "fieldName": "城市",
        "datasetId": 7,
        "label": "城市"
      }
    ],
    "pathAttr": [
    ],
    "description": "",
    "category": "measure",
    "label": "988test",
    "expr": {
      "kind": "formula",
      "op": "SUM({销售额})",
      "type": "number",
      "value": "SUM({销售额})",
      "isAggregate": true,
      "isConstant": false,
      "allFieldsFromBaseDataset": true
    },
    "type": "number",
    "config": {
    }
  }
}

更新业务指标的部分信息

请求URL

http

POST /api/apps/{appId}/datasets/{datasetId}/measures/patch?fieldName= HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

request body 请求体

业务指标结构说明

URL 参数

字段	类型	是否必须	说明
force	BOOLEAN	否	是否强制更新数据集

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
data	OBJECT	业务指标共同结构见业务指标结构说明

接口示例

RequestResponse

http

POST /api/apps/119287/datasets/7/measures/patch?fieldName=c1 HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
  "extraOptions":{"t1":18}
}

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "msg": "success",
  "data": {
    "datasetId": 7,
    "fieldName": "c1",
    "appId": 119287,
    "tags": {
    },
    "updatedBy": 11549,
    "updatedAt": "2023-02-10 11:16:53",
    "dimensions": [
      {
        "fieldName": "省/自治区",
        "datasetId": 7,
        "label": "省/自治区"
      },
      {
        "fieldName": "城市",
        "datasetId": 7,
        "label": "城市"
      }
    ],
    "pathAttr": [
    ],
    "description": "",
    "category": "measure",
    "label": "988test",
    "expr": {
      "kind": "formula",
      "op": "SUM({销售额})",
      "type": "number",
      "value": "SUM({销售额})",
      "isAggregate": true,
      "isConstant": false,
      "allFieldsFromBaseDataset": true
    },
    "type": "number",
    "config": {
    },
    "extraOptions":{"t1":18}
  }
}

分页查询业务指标

请求URL

http

POST /api/measures/query HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

URL 参数

字段	类型	是否必须	说明
offset	LONG	否	分页偏移量
limit	LONG	否	分页条数限制
queryDimensionType	BOOLEAN	否	是否查询分析维度字段类型

request body 请求体

字段	类型	是否必须	说明
folderId	LONG	是	指标文件夹id，静态主题域和动态主题域都走该接口
creators	ARRAY	否	指标创建者id数组
datasetKeys	ARRAY	否	appId与数据集id元组的数组
orderBy	STRING	否	排序字段
orderType	STRING	否	排序类型 desc、asc
q	STRING	否	模糊查询指标名称
withAction	BOOLEAN	否	是否携带权限
onlineStatus	ARRAY	否	指标上线、下线状态数组

当 folderId 指向动态主题域时，接口行为如下：

继续复用 POST /api/measures/query
后端会根据主题域目录配置的 measureSubject.connectionId 实时调用第三方指标平台
measureSubject.queryParams、measureSubject.requestBody 会透传给 Groovy fetchMetrics(request)
返回结果仍然保持当前 MetricDto 结构，但主题域内的指标不再依赖静态 metric_folder 绑定

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
data	OBJECT 数组	业务指标共同结构见业务指标结构说明

接口示例

RequestResponse

http

POST /api/measures/query?limit=1000&offset=0 HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

{
    "folderId": 4821,
    "orderBy": "updatedAt",
    "orderType": "desc",
    "withAction": true,
    "datasetKeys": [
        [
            "131203",
            "1"
        ]
    ],
    "creators": [
        23128,
        11549
    ],
    "onlineStatus": [
        "true"
    ],
    "q": ""
}

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "msg": "success",
  "data": [
    {
      "datasetId": 7,
      "fieldName": "c1",
      "appId": 119287,
      "tags": {
      },
      "createdBy": 11549,
      "createdAt": "2023-02-10 11:04:12",
      "updatedBy": 11549,
      "updatedAt": "2023-02-10 11:16:53",
      "dimensions": [
        {
          "fieldName": "省/自治区",
          "datasetId": 7,
          "label": "省/自治区",
          "type": "string"
        },
        {
          "fieldName": "城市",
          "datasetId": 7,
          "label": "城市",
          "type": "string"
        }
      ],
      "pathAttr": [
      ],
      "description": "",
      "category": "measure",
      "label": "988test",
      "expr": {
        "kind": "formula",
        "op": "SUM({销售额})",
        "type": "number",
        "value": "SUM({销售额})",
        "isAggregate": true,
        "isConstant": false,
        "allFieldsFromBaseDataset": true
      },
      "type": "number",
      "creator": {
        "id": 11549,
        "name": "陈静",
        "email": "111@qq.com",
        "avatar": "",
        "loginName": "chenjing"
      },
      "updater": {
        "id": 11549,
        "name": "陈静",
        "email": "111@qq.com",
        "avatar": "",
        "loginName": "chenjing"
      },
      "action": "|admin|read|write|",
      "accessCount": 4,
      "lastAccessedAt": "2023-02-10 11:16:47",
      "config": {
      }
    },
    {
      "datasetId": 7,
      "fieldName": "c2",
      "appId": 119287,
      "tags": {
      },
      "createdBy": 11549,
      "createdAt": "2023-02-10 11:08:42",
      "updatedBy": 11549,
      "updatedAt": "2023-02-10 11:08:42",
      "dimensions": [
        {
          "fieldName": "省/自治区",
          "datasetId": 7,
          "label": "省/自治区",
          "type": "string"
        },
        {
          "fieldName": "城市",
          "datasetId": 7,
          "label": "城市",
          "type": "string"
        }
      ],
      "pathAttr": [
      ],
      "description": "",
      "category": "measure",
      "label": "988test1",
      "expr": {
        "kind": "formula",
        "op": "SUM({销售额})",
        "type": "number",
        "value": "SUM({销售额})",
        "isAggregate": true,
        "isConstant": false,
        "allFieldsFromBaseDataset": true
      },
      "type": "number",
      "creator": {
        "id": 11549,
        "name": "陈静",
        "email": "111@qq.com",
        "avatar": "",
        "loginName": "chenjing"
      },
      "updater": {
        "id": 11549,
        "name": "陈静",
        "email": "111@qq.com",
        "avatar": "",
        "loginName": "chenjing"
      },
      "action": "|admin|read|write|",
      "accessCount": 4,
      "lastAccessedAt": "2023-02-10 11:16:47",
      "config": {
      }
    }
  ],
  "totalHits": 2,
  "offset": 0
}

分页查询指定数据集内的业务指标

请求URL

http

POST /api/apps/{appId}/datasets/{datasetId}/measures/query HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

URL 参数

字段	类型	是否必须	说明
appId	LONG	是	应用id
datasetId	LONG	是	数据集id
offset	LONG	否	分页偏移量
limit	LONG	否	分页条数限制
orderBy	STRING	否	排序字段
orderType	STRING	否	排序类型
queryDimensionType	BOOLEAN	否	是否查询分析维度字段类型

request body 请求体

字段	类型	是否必须	说明
q	STRING	否	模糊查询指标名称
category	STRING	是	固定值 "category"
groupList	ARRAY	否	指标分组的数组

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
data	OBJECT 数组	业务指标共同结构见业务指标结构说明

接口示例

RequestResponse

http

POST /api/apps/1/datasets/1/measures/query?orderBy=updatedAt&orderType=desc&limit=1000&offset=0 HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

{
    "q": null,
    "groupList": [
        "分组1"
    ],
    "category": "measure"
}

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "msg": "success",
  "data": [
    {
      "datasetId": 7,
      "fieldName": "c1",
      "appId": 119287,
      "tags": {
      },
      "createdBy": 11549,
      "createdAt": "2023-02-10 11:04:12",
      "updatedBy": 11549,
      "updatedAt": "2023-02-10 11:16:53",
      "dimensions": [
        {
          "fieldName": "省/自治区",
          "datasetId": 7,
          "label": "省/自治区",
          "type": "string"
        },
        {
          "fieldName": "城市",
          "datasetId": 7,
          "label": "城市",
          "type": "string"
        }
      ],
      "pathAttr": [
      ],
      "description": "",
      "category": "measure",
      "label": "988test",
      "expr": {
        "kind": "formula",
        "op": "SUM({销售额})",
        "type": "number",
        "value": "SUM({销售额})",
        "isAggregate": true,
        "isConstant": false,
        "allFieldsFromBaseDataset": true
      },
      "type": "number",
      "creator": {
        "id": 11549,
        "name": "陈静",
        "email": "111@qq.com",
        "avatar": "",
        "loginName": "chenjing"
      },
      "updater": {
        "id": 11549,
        "name": "陈静",
        "email": "111@qq.com",
        "avatar": "",
        "loginName": "chenjing"
      },
      "action": "|admin|read|write|",
      "accessCount": 4,
      "lastAccessedAt": "2023-02-10 11:16:47",
      "config": {
      }
    },
    {
      "datasetId": 7,
      "fieldName": "c2",
      "appId": 119287,
      "tags": {
      },
      "createdBy": 11549,
      "createdAt": "2023-02-10 11:08:42",
      "updatedBy": 11549,
      "updatedAt": "2023-02-10 11:08:42",
      "dimensions": [
        {
          "fieldName": "省/自治区",
          "datasetId": 7,
          "label": "省/自治区",
          "type": "string"
        },
        {
          "fieldName": "城市",
          "datasetId": 7,
          "label": "城市",
          "type": "string"
        }
      ],
      "pathAttr": [
      ],
      "description": "",
      "category": "measure",
      "label": "988test1",
      "expr": {
        "kind": "formula",
        "op": "SUM({销售额})",
        "type": "number",
        "value": "SUM({销售额})",
        "isAggregate": true,
        "isConstant": false,
        "allFieldsFromBaseDataset": true
      },
      "type": "number",
      "creator": {
        "id": 11549,
        "name": "陈静",
        "email": "111@qq.com",
        "avatar": "",
        "loginName": "chenjing"
      },
      "updater": {
        "id": 11549,
        "name": "陈静",
        "email": "111@qq.com",
        "avatar": "",
        "loginName": "chenjing"
      },
      "action": "|admin|read|write|",
      "accessCount": 4,
      "lastAccessedAt": "2023-02-10 11:16:47",
      "config": {
      }
    }
  ],
  "totalHits": 2,
  "offset": 0
}

根据ID查询业务指标

请求URL

http

GET /api/apps/{appId}/datasets/{datasetId}/measures?fieldName= HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
data	OBJECT	业务指标共同结构见业务指标结构说明

接口示例

RequestResponse

http

GET /api/apps/{appId}/datasets/{datasetId}/measures?fieldName=c1 HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "msg": "success",
  "data": {
    "datasetId": 7,
    "fieldName": "c1",
    "appId": 119287,
    "tags": {
    },
    "dimensions": [
      {
        "fieldName": "省/自治区",
        "datasetId": 7,
        "label": "省/自治区"
      },
      {
        "fieldName": "城市",
        "datasetId": 7,
        "label": "城市"
      }
    ],
    "pathAttr": [
    ],
    "description": "",
    "category": "measure",
    "label": "988test",
    "expr": {
      "kind": "formula",
      "op": "SUM({销售额})",
      "type": "number",
      "value": "SUM({销售额})",
      "isAggregate": true,
      "isConstant": false,
      "allFieldsFromBaseDataset": true
    },
    "type": "number",
    "action": "admin|read|write||",
    "config": {
    }
  }
}

重写业务指标表达式

请求URL

http

POST /api/apps/{appId}/datasets/{datasetId}/measures/rewrite-formula HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

request body 请求体

HE 表达式，详情参照HE 的数据集函数

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
data	OBJECT	业务指标共同结构见业务指标结构说明

接口示例

RequestResponse

http

POST /api/apps/125615/datasets/3/measures/rewrite-formula HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
  "kind": "formula",
  "op": "COUNT({{12}}.{客户类型}) FILTER (WHERE TRUNC_MONTH({发货日期}) < {{%v_month}} AND in({c10}, {{%多值动态地区}}))",
  "type": "number",
  "value": "COUNT({{客户}}.{客户类型}) FILTER (WHERE TRUNC_MONTH({发货日期}) < {{%v_month}} AND in({caseWhen}, {{%多值动态地区}}))",
  "isAggregate": true,
  "isConstant": false,
  "allFieldsFromBaseDataset": false
}

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "msg": "success",
  "data": {
    "kind": "formula",
    "op": "COUNT({{12}}.{客户类型}) FILTER (WHERE TRUNC_MONTH({发货日期}) < {{%v_month}} AND in({c10}, {{%多值动态地区}}))",
    "value": "COUNT({{客户}}.{客户类型}) FILTER (WHERE TRUNC_MONTH({发货日期}) < {{%v_month}} AND in({caseWhen}, {{%多值动态地区}}))",
    "isAggregate": true
  }
}

重写图表表达式

请求URL

http

POST /api/apps/{appId}/rewrite-formula HTTP/1.1
Content-Type: application/json

请求参数

request body 请求体

json

{
  "measureSubjectId": 1001,
  "dataAppId": 2001,
  "datasetId": 3001,
  "options": {
    "axes": [],
    "sourceMeasureKeys": [11, 12]
  },
  "formula": {
    "kind": "formula",
    "op": "sum({销售额}) / {{%target}}"
  }
}

appId：图表所在应用 ID
measureSubjectId：业务指标模式下的主题域 ID；为空时按数据集模式处理
dataAppId / datasetId：数据集模式下直接使用；业务指标模式下会结合 options.sourceMeasureKeys / options.axes 解析真实数据源
options.axes：用于补充公式中的 reference / uid 上下文
formula：待重写的 HE 公式

返回对象的格式说明

返回值与“重写业务指标表达式”接口一致，data 为重写后的 HE formula 结构。

根据ID删除业务指标

请求URL

http

DELETE /api/apps/{appId}/datasets/{datasetId}/measures?fieldName= HTTP/1.1

请求参数

URL 参数

字段	类型	是否必须	说明
force	BOOLEAN	否	是否强制更新数据集

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
msg	STRING	成功返回 success

接口示例

RequestResponse

http

DELETE /api/apps/119287/datasets/7/measures?fieldName=c2 HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "msg": "success"
}

把指标添加到主题域的目录中

仅静态主题域支持该接口；动态主题域不允许再通过 metric_folder 手工维护指标成员。

请求URL

http

POST /api/folders/{folderId}/metric-folders HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

URL 参数

字段	类型	是否必须	说明
folderId	INTEGER	是	文件夹的 id

request body 请求体

指标和文件夹对应关系的数组，数组的元素是描述关系的实体，下面是实体的字段信息：

字段	类型	是否必须	说明
appId	INTEGER	是	指标所在的应用 id
datasetId	INTEGER	是	指标所在的数据集 id
fieldName	STRING	是	指标的字段名

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
msg	STRING	成功返回 success

接口示例

RequestResponse

http

POST /api/folders/109/metric-folders HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
[
  {
    "appId": 2471,
    "datasetId": 1,
    "fieldName": "c1"
  },
  {
    "appId": 2471,
    "datasetId": 1,
    "fieldName": "c0"
  }
]

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "data": 2,
  "msg": "success"
}

从主题域的目录中删除指标

仅静态主题域支持该接口；动态主题域的指标列表来自外部实时查询，不支持手工删除成员。

请求URL

http

POST /api/folders/{folderId}/metric-folders/remove HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

URL 参数

字段	类型	是否必须	说明
folderId	INTEGER	是	文件夹的 id

request body 请求体

指标和文件夹对应关系的数组，数组的元素是描述关系的实体，下面是实体的字段信息：

字段	类型	是否必须	说明
appId	INTEGER	是	指标所在的应用 id
datasetId	INTEGER	是	指标所在的数据集 id
fieldName	STRING	是	指标的字段名

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
msg	STRING	成功返回 success

接口示例

RequestResponse

http

POST /api/folders/109/metric-folders/remove HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
[
  {
    "appId": 2471,
    "datasetId": 1,
    "fieldName": "c1"
  }
]

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "data": 1,
  "msg": "success"
}

切换主题域中指标上线、下线

仅静态主题域支持该接口；动态主题域返回的指标默认按实时在线数据处理。

请求URL

http

POST /api/folders/{folderId}/metric-folders/switch HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

URL 参数

字段	类型	是否必须	说明
folderId	INTEGER	是	主题域的 id

request body 请求体

指标和文件夹对应关系的数组，数组的元素是描述关系的实体，下面是实体的字段信息：

字段	类型	是否必须	说明
appId	INTEGER	是	指标所在的应用 id
datasetId	INTEGER	是	指标所在的数据集 id
fieldName	STRING	是	指标的字段名
isOnline	BOOL	是	true 表示上线，false 表示下线

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
msg	STRING	成功返回 success

接口示例

RequestResponse

http

POST /api/folders/109/metric-folders/switch HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
[
  {
    "appId": 2471,
    "datasetId": 1,
    "fieldName": "c1",
    "isOnline": "false"
  }
]

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "data": 1,
  "msg": "success"
}

查询主题域分析上下文

请求URL

http

POST /api/folders/{folderId}/measures/analysis-context HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

URL 参数

字段	类型	是否必须	说明
folderId	INTEGER	是	主题域文件夹 id

request body 请求体

字段	类型	是否必须	说明
selectedMeasures	List<DatasetFieldDto>	否	已选指标（静态主题域通常只需传 `metric_folder.id`；动态主题域可仅传 `fieldName`）
selectedFields	List<DatasetFieldDto>	否	已选维度
candidateMeasures	List<DatasetFieldDto>	否	候选指标列表（静态主题域通常只需传 `metric_folder.id`；动态主题域可仅传 `fieldName`）

说明：

只要请求里传了 candidateMeasures，后端都会先补全候选指标详情（无论是否同时传 selectedMeasures/selectedFields）。
普通主题域下，compatibleMeasures 只会从与当前分析 scope 同一个 appId + datasetId 的候选指标中产生；这里的“同一个数据集”按指标自身的 appId + datasetId 判断，不再按 mainDataset 归并。
selectedMeasures 即使没有同时回显在 candidateMeasures 里，后端也会按当前主题域继续补全并参与分析；只有当前主题域下确实不存在的脏指标才会被忽略。
unionFields 始终基于补全后的候选指标计算，与 compatibleMeasures 是否为空无关。
动态主题域下，第三方指标元信息按 metricCode -> fieldName、metricName -> label 映射；不会再额外构造业务指标 id，前端应按“有 id 用 id，否则用 fieldName”处理。

请求组合语义：

请求组合	compatibleMeasures	intersectionFields	unionFields
只传 `candidateMeasures`	不做兼容筛选，通常为空/不返回	通常为空/不返回	返回这批候选指标的可分析维度并集
`selectedFields`（可选再带 `candidateMeasures`，`selectedMeasures` 为空）	返回可分析维度完整包含全部 `selectedFields` 的候选指标；若未传 `candidateMeasures`，后端会自动取当前主题域下、同一 `appId + datasetId` 的在线指标作为候选	返回这些 `compatibleMeasures` 的可分析维度并集，便于继续扩展维度	返回候选指标维度并集
`selectedMeasures`（可选再带 `candidateMeasures`，`selectedFields` 为空）	返回与已选指标可一起分析的指标；若未传 `candidateMeasures`，后端会自动取当前主题域下、同一 `appId + datasetId` 的在线指标作为候选。候选指标只要与“已选指标公共维度集合”有任一交集即可入选；若已选指标之间没有公共维度，则回退为同数据集候选指标全部可兼容	返回已选指标自身的公共维度；若没有公共维度，稳定返回 `[]`	返回候选指标维度并集
`selectedMeasures` + `selectedFields`（可选再带 `candidateMeasures`）	先要求 `selectedFields` 必须全部属于“已选指标公共维度集合”；否则 `compatibleMeasures` 为空。满足前置条件后，再从候选指标里筛出可分析维度完整包含全部 `selectedFields` 的指标；若未传 `candidateMeasures`，后端会自动取当前主题域下、同一 `appId + datasetId` 的在线指标作为候选	仍然返回已选指标自身的公共维度，不再取 `compatibleMeasures` 的维度交集；若没有公共维度，返回 `[]`	返回候选指标维度并集

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
msg	STRING	成功返回 success
data	MeasureDimDto	分析上下文结果

返回的 MeasureDimDto 结构：

字段	类型	说明
candidateMeasures	List<DatasetFieldDto>	候选指标轻量引用；静态主题域通常包含 `appId/datasetId/fieldName`，动态主题域至少包含 `fieldName`
compatibleMeasures	List<DatasetFieldDto>	可兼容指标轻量引用。若 `selectedMeasures` 非空，表示“能与已选指标一起分析的候选指标”；若仅传 `selectedFields`，表示“可完整覆盖这些已选维度的候选指标”
measures	List<DatasetFieldDto>	指标完整信息集合（去重，包含完整 dimensions）
fields	List<DatasetFieldDto>	维度完整信息集合（去重）
intersectionFields	List<DatasetFieldDto>	维度轻量引用。若 `selectedMeasures` 非空，表示“已选指标自身的公共可分析维度”；若仅传 `selectedFields`，表示“当前 `compatibleMeasures` 的可分析维度并集”。没有公共维度时返回 `[]`
unionFields	List<DatasetFieldDto>	候选指标维度并集的轻量引用；静态主题域通常包含 `appId/datasetId/fieldName`，动态主题域至少包含 `fieldName`
measureSubjectId	LONG	主题域文件夹 id
measureSubjectTitle	STRING	主题域名称
appId	LONG	解析出的 appId（若可确定）
datasetId	LONG	解析出的 datasetId（若可确定）
appParams	List<AppParam>	解析出的数据包所属应用参数列表
functions	List<STRING>	当请求 query 参数 `functions=true` 时返回，数据集所支持的函数 key 列表（与数据集 `/functions` 接口一致）

接口示例

RequestResponse

http

POST /api/folders/109/measures/analysis-context HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
  "selectedMeasures": [
    { "id": 123 },
    { "id": 456 }
  ],
  "selectedFields": [
    {
      "appId": 2471,
      "datasetId": 1,
      "fieldName": "region"
    }
  ],
  "candidateMeasures": [
    { "id": 123 },
    { "id": 456 },
    { "id": 789 }
  ],
  "needUnionFields": true
}

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "data": {
    "candidateMeasures": [
      { "appId": 2471, "datasetId": 1, "fieldName": "total_sales" },
      { "appId": 2471, "datasetId": 1, "fieldName": "profit" },
      { "appId": 2471, "datasetId": 1, "fieldName": "order_cnt" }
    ],
    "compatibleMeasures": [
      { "appId": 2471, "datasetId": 1, "fieldName": "total_sales" },
      { "appId": 2471, "datasetId": 1, "fieldName": "profit" }
    ],
    "measures": [
      {
        "appId": 2471,
        "datasetId": 1,
        "fieldName": "total_sales",
        "label": "总销售额",
        "dimensions": [
          { "appId": 2471, "datasetId": 1, "fieldName": "region", "label": "地区", "type": "string" },
          { "appId": 2471, "datasetId": 1, "fieldName": "category", "label": "品类", "type": "string" }
        ]
      },
      {
        "appId": 2471,
        "datasetId": 1,
        "fieldName": "profit",
        "label": "利润",
        "dimensions": [
          { "appId": 2471, "datasetId": 1, "fieldName": "region", "label": "地区", "type": "string" }
        ]
      },
      {
        "appId": 2471,
        "datasetId": 1,
        "fieldName": "order_cnt",
        "label": "订单数",
        "dimensions": [
          { "appId": 2471, "datasetId": 1, "fieldName": "category", "label": "品类", "type": "string" }
        ]
      }
    ],
    "fields": [
      { "appId": 2471, "datasetId": 1, "fieldName": "region", "label": "地区", "type": "string" },
      { "appId": 2471, "datasetId": 1, "fieldName": "category", "label": "品类", "type": "string" }
    ],
    "intersectionFields": [
      { "appId": 2471, "datasetId": 1, "fieldName": "region" }
    ],
    "unionFields": [
      { "appId": 2471, "datasetId": 1, "fieldName": "region" },
      { "appId": 2471, "datasetId": 1, "fieldName": "category" }
    ],
    "appParams": [
      {
        "id": 9001,
        "name": "target_month",
        "appId": 2471
      }
    ],
    "measureSubjectId": 109,
    "appId": 2471,
    "datasetId": 1
  },
  "msg": "success"
}

根据标识查询主题域中的指标

请求URL

http

GET /api/folders/{folderId}/measures/{measureId} HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

URL 参数

字段	类型	是否必须	说明
folderId	INTEGER	是	主题域文件夹 id
measureId	STRING	是	普通主题域传静态指标 id（`metric_folder.id`）；动态主题域传指标 `fieldName`

说明：

普通主题域下，measureId 仍按原有静态指标 id 处理。
动态主题域下，measureId 不再要求是数字，后端按 fieldName 精确获取对应指标。

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
msg	STRING	成功返回 success
data	DatasetFieldDto	指标详情

接口示例

动态主题域 Request动态主题域 Response

http

GET /api/folders/109/measures/ext_gmv HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "data": {
    "fieldName": "ext_gmv",
    "label": "dyn-GMV",
    "category": "measure",
    "folderId": 109
  },
  "msg": "success"
}

主题域中指标的血缘关系

请求URL

http

GET /api/folders/{folderId}/measures/{measureId}/lineage HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

URL 参数

字段	类型	是否必须	说明
folderId	INTEGER	是	主题域的 id
measureId	INTEGER	是	指标的 id

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
data	OBJECT	见数据集血缘结构说明

接口示例

RequestResponse

http

GET /api/folders/22/measures/10786/lineage HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
    "code": 0,
    "msg": "success",
    "data": {
        "lineageGraph": {
            "vertices": [
                {
                    "vertexId": 0,
                    "appId": 750,
                    "datasetId": 7,
                    "title": "多表联合_A left join B ",
                    "refreshAt": "2025-01-09 09:54:09",
                    "type": "measure",
                    "fieldName": "m2",
                    "fieldLabel": "m2-0109-data-api",
                    "importType": 0
                },
                {
                    "vertexId": 1,
                    "appId": 750,
                    "datasetId": 7,
                    "title": "多表联合_A left join B ",
                    "type": "field",
                    "fieldName": "部门成立日期_2",
                    "fieldLabel": "部门成立日期",
                    "importType": 0
                },
                {
                    "vertexId": 2,
                    "appId": 750,
                    "datasetId": 7,
                    "title": "多表联合_A left join B ",
                    "type": "field",
                    "fieldName": "业绩金额_2",
                    "fieldLabel": "业绩金额",
                    "importType": 0
                }
            ],
            "edges": [
                {
                    "left": 1,
                    "right": 0,
                    "lineageType": [
                        "FILTER"
                    ]
                },
                {
                    "left": 2,
                    "right": 0,
                    "lineageType": [
                        "FORMULA"
                    ]
                }
            ]
        }
    }
}

获取主题域中指标的数据

请求URL

http

GET /api/folders/{folderId}/measures/{measureId}/data HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

URL 参数

字段	类型	是否必须	说明
folderId	INTEGER	是	主题域的 id
measureId	INTEGER	是	指标的 id
withAllDims	BOOLEAN	否	是否需要业务指标定义的所有分析维度，默认为 false

withAllDims 为 false，会根据业务指标的默认图表返回数据；withAllDims 为true，会根据业务指标配置的所有分析维度返回数据。

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
data	OBJECT	见数据集数据 datasetResultDto

接口示例

RequestResponse

http

GET /api/folders/22/measures/10786/data HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
    "code": 0,
    "msg": "success",
    "data": {
        "data": [
            [
                "人力资源部",
                4377
            ],
            [
                "财务部",
                22581
            ]
        ],
        "pagable": true,
        "importSwitchable": true,
        "schema": [
            {
                "fieldName": "部门_1_0",
                "type": "string"
            },
            {
                "fieldName": "2_1",
                "type": "number"
            }
        ],
        "lastQueryTime": "2025-01-09T09:54:17.672455"
    }
}

获取主题域中指标的 sql

请求URL

http

GET /api/folders/{folderId}/measures/{measureId}/sql-debug HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

URL 参数

字段	类型	是否必须	说明
folderId	INTEGER	是	主题域的 id
measureId	INTEGER	是	指标的 id
withAllDims	BOOLEAN	否	是否需要业务指标定义的所有分析维度，默认为 false

withAllDims 为 false，会根据业务指标的默认图表返回 sql；withAllDims 为true，会根据业务指标配置的所有分析维度返回 sql。

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
data	OBJECT	字符串数组

接口示例

RequestResponse

http

GET /api/folders/22/measures/10786/sql-debug HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

http

HTTP/1.1 200 Ok
Content-Type: application/json

{
    "version": "5.4-SNAPSHOT@@git.commit.id.abbrev@#b1e1b9e",
    "code": 0,
    "msg": "success",
    "data": [
        "SELECT `dataset_7`.`部门_1` AS `部门_1_0`, `dataset_7`.`子部门_1` AS `子部门_1_1`, `dataset_7`.`部门_2` AS `部门_2_2`, sum(`dataset_7`.`业绩金额_2`) AS `m2_3` FROM (SELECT `01JE553G57QSXQXR9F58NBERR4`.`部门` AS `部门_1`, `01JE553G57QSXQXR9F58NBERR4`.`子部门` AS `子部门_1`, `01JE553HYD9CWBQ8A8JCPW8X89`.`部门` AS `部门_2`, `01JE553HYD9CWBQ8A8JCPW8X89`.`业绩金额` AS `业绩金额_2` FROM (SELECT * FROM `kuangjiashuai`.`A` `dataset_1` WHERE `dataset_1`.`部门` != '销售部') `01JE553G57QSXQXR9F58NBERR4` LEFT JOIN (SELECT * FROM `kuangjiashuai`.`B` `dataset_2` WHERE `dataset_2`.`部门` != '{{%部门参数}}' AND `dataset_2`.`部门` != '市场部' AND year(`dataset_2`.`部门成立日期`) IN (2017, 2018, 2019)) `01JE553HYD9CWBQ8A8JCPW8X89` ON `01JE553G57QSXQXR9F58NBERR4`.`部门` = `01JE553HYD9CWBQ8A8JCPW8X89`.`部门` WHERE `01JE553HYD9CWBQ8A8JCPW8X89`.`部门` != '市场部' AND year(`01JE553HYD9CWBQ8A8JCPW8X89`.`部门成立日期`) IN (2017, 2018, 2019)) `dataset_7` GROUP BY 1, 2, 3 ORDER BY isnull(`部门_1_0`), `部门_1_0` ASC, isnull(`子部门_1_1`), `子部门_1_1` ASC, isnull(`部门_2_2`), `部门_2_2` ASC LIMIT 1000"
    ]
}

业务指标 ​

资源说明 ​

业务指标的定义 ​

业务指标结构说明 ​

Metric ​

MetricDto ​

接口说明 ​

MeasureDimDto 结构（分析上下文相关） ​

新增业务指标 ​

请求URL ​

请求参数 ​

request body 请求体 ​

返回对象的格式说明 ​

接口示例 ​

复制业务指标 ​

请求URL ​

请求参数 ​

request body 请求体 ​

返回对象的格式说明 ​

接口示例 ​

更新业务指标 ​

请求URL ​

请求参数 ​

request body 请求体 ​

URL 参数 ​

返回对象的格式说明 ​

接口示例 ​

更新业务指标的部分信息 ​

请求URL ​

请求参数 ​

request body 请求体 ​

URL 参数 ​

返回对象的格式说明 ​

接口示例 ​

分页查询业务指标 ​

请求URL ​

请求参数 ​

URL 参数 ​

request body 请求体 ​

返回对象的格式说明 ​

接口示例 ​

分页查询指定数据集内的业务指标 ​

请求URL ​

请求参数 ​

URL 参数 ​

request body 请求体 ​

返回对象的格式说明 ​

接口示例 ​

根据ID查询业务指标 ​

请求URL ​

返回对象的格式说明 ​

接口示例 ​

重写业务指标表达式 ​

请求URL ​

请求参数 ​

request body 请求体 ​

返回对象的格式说明 ​

接口示例 ​

重写图表表达式 ​

请求URL ​

请求参数 ​

request body 请求体 ​

返回对象的格式说明 ​

根据ID删除业务指标 ​

请求URL ​

请求参数 ​

URL 参数 ​

返回对象的格式说明 ​

接口示例 ​

把指标添加到主题域的目录中 ​

请求URL ​

请求参数 ​

URL 参数 ​

request body 请求体 ​

返回对象的格式说明 ​

接口示例 ​

从主题域的目录中删除指标 ​

请求URL ​

请求参数 ​

URL 参数 ​

业务指标

资源说明

业务指标的定义

业务指标结构说明

Metric

MetricDto

接口说明

MeasureDimDto 结构（分析上下文相关）

新增业务指标

请求URL

请求参数

request body 请求体

返回对象的格式说明

接口示例

复制业务指标

请求URL

请求参数

request body 请求体

返回对象的格式说明

接口示例

更新业务指标

请求URL

请求参数

request body 请求体

URL 参数

返回对象的格式说明

接口示例

更新业务指标的部分信息

请求URL

请求参数

request body 请求体

URL 参数

返回对象的格式说明

接口示例

分页查询业务指标

请求URL

请求参数

URL 参数

request body 请求体

返回对象的格式说明

接口示例

分页查询指定数据集内的业务指标

请求URL

请求参数

URL 参数

request body 请求体

返回对象的格式说明

接口示例

根据ID查询业务指标

请求URL

返回对象的格式说明

接口示例

重写业务指标表达式

请求URL

请求参数

request body 请求体

返回对象的格式说明

接口示例

重写图表表达式

请求URL

请求参数

request body 请求体

返回对象的格式说明

根据ID删除业务指标

请求URL

请求参数

URL 参数

返回对象的格式说明

接口示例

把指标添加到主题域的目录中

请求URL

请求参数

URL 参数

request body 请求体

返回对象的格式说明

接口示例

从主题域的目录中删除指标

请求URL

请求参数

URL 参数