数据集字段

数据集字段说明

数据集字段定义

数据集字段是数据集的重要组成部分，描述了数据集提供的所有字段属性，分为原始字段和新增字段两类。

数据集字段结构说明

字段	类型	描述
id	LONG	字段的 id
datasetId	LONG	字段所在的数据集的 id
fieldName	STRING	字段名
type	STRING	字段类型，字段类型包含： number，date，string，bool，json，unknown 6种
nativeType	STRING	字段数据源内部类型，和具体数据源相关，比如BIGINT，VARCHAR等
originType	STRING	字段原始类型，字段类型包含： number，date，string，bool，json，unknown 6种
suggestedTypes	STRING 数组	字段允许选择的类型，类型包含： number，date，string，bool，json，unknown 6种
visible	BOOL	字段是否隐藏，包括 true 和 false
label	STRING	字段的别名
expr	HE	字段的计算表达式，原始字段没有此项值
expr.value	STRING	当 expr 的 kind 为 formula时， value显示用户可读的表达式
config	OBJECT	字段的配置
config.formatter	OBJECT	字段的格式
config.formatter.decimal	INTEGER	数字字段值的小数位数
config.formatter.percent	STRING	显示百分比设置为"%"，不显示为""
config.formatter.prefix	STRING	字段值的前缀
config.formatter.suffix	STRING	字段值的后缀
config.formatter.unit	STRING	字段值的单位，包含：亿，千万，百万，万，千，百，M，K
config.formatter.thousands	BOOL	显示千分位分隔符, 启用设置为true
config.formatter.scientificNotation	BOOL	科学计数法，启用设置为true
hsVersion	INTEGER	可选，本次编辑的版本号，从0开始，修改前先GET待修改资源获取当前版本号，修改时带上刚刚获取的版本号，服务端会检查并发冲突。不带版本号不检查并发冲突。
comment	STRING	数据库表格的字段描述，只有直连的table有，不能编辑
description	STRING	用户编辑的字段描述，默认为空
inUse	BOOL	标记这个字段是否被使用

数据集字段接口说明

新增字段

请求URL

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

请求参数

URL 参数

字段	类型	是否必须	说明
appId	INTEGER	是	数据集所在的应用 ID
datasetId	INTEGER	是	数据集 ID

Request Body 参数

见数据集字段结构说明

返回对象的格式说明

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

接口示例1: 新增字段

Request

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

// Request Body:
{
    "options": {
        "label": "测试",
        "visible": true,
        "expr": {
            "kind": "formula",
            "op": "{{数据集1}}.{id} + {{数据集1}}.{idplus}",
            "value": "{{数据集1}}.{id} + {{数据集1}}.{idplus}"
        }
    }
}

Response

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

{
    "version": "version@9a5e106#6730f0d",
    "code": 0,
    "msg": "success",
    "data": {
        "id": 3797644,
        "datasetId": 1,
        "fieldName": "c0",
        "appId": 46176,
        "originType": "integer",
        "type": "number",
        "config": {
            "dialectName": "EngineDialect"
        },
        "label": "测试",
        "visible": true,
        "expr": {
            "kind": "formula",
            "op": "{{数据集1}}.{id} + {{数据集1}}.{idplus}",
            "value": "{{数据集1}}.{id} + {{数据集1}}.{idplus}"
        },
        "nativeType": "int4",
        "suggestedTypes": [
            "number",
            "string"
        ],
        "detectedType": "integer",
        "defaultAggrType": "sum",
        "basicType": "number",
        "formula": "{{数据集1}}.{id} + {{数据集1}}.{idplus}"
    }
}

获取数据集所有字段

请求URL

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

请求参数

URL 参数

字段	类型	是否必须	说明
appId	INTEGER	是	数据集所在的应用 ID
datasetId	INTEGER	是	数据集 ID
hideInvisible	BOOL	否	是否隐藏不可见字段，默认是 false
inUseOnly	BOOL	否	只列出被使用的字段，默认是 false
markInUse	BOOL	否	返回所有的字段，并且被使用的字段会加上 inUse=true 的标记，默认是 false

返回对象的格式说明

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

批量更新数据集的字段

请求URL

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

请求参数

URL 参数

字段	类型	是否必须	说明
appId	INTEGER	是	数据集所在的应用 ID
datasetId	INTEGER	是	数据集 ID

response body 请求体

多字段的配置信息

返回对象的格式说明

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

接口示例1: 批量更新字段

PUT /api/apps/1/datasets/1/fields HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
    "options": {
        "schema": [
            {
                "datasetId": "1",
                "fieldName": "id",
                "hsVersion": 6,
                "originType": "integer",
                "type": "number",
                "description": "序号",
                "config": {
                    "dialectName": "EngineDialect",
                    "formatter": {
                        "scientificNotation": true,
                        "unit": "",
                        "nullReplace": {
                            "op": 0,
                            "kind": "constant",
                            "type": "number"
                        },
                        "prefix": "",
                        "suffix": "自动",
                        "decimal": 2,
                        "thousands": false,
                        "percent": ""
                    }
                },
                "label": "id",
                "basicType": "number",
                "visible": true,
                "nativeType": "bigserial",
                "suggestedTypes": [
                    "number",
                    "string"
                ],
                "detectedType": "integer",
                "defaultAggrType": "sum"
            },
            {
                "datasetId": "1",
                "fieldName": "province_code",
                "hsVersion": 6,
                "originType": "string",
                "type": "string",
                "description": "省份代码",
                "config": {
                    "seperator": " ",
                    "dialectName": "EngineDialect"
                },
                "label": "province_code",
                "basicType": "string",
                "visible": true,
                "nativeType": "varchar",
                "suggestedTypes": [
                    "number",
                    "string"
                ],
                "detectedType": "number",
                "defaultAggrType": "count"
            }
        ]
    },
    "hsVersion": 13
}

获取 {id} 数据集的 {fieldName} 字段

请求URL

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

请求参数

URL 参数

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

返回对象的格式说明

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

更新 {id} 数据集的 {fieldName} 字段

可用于更新新增字段的表达式

请求URL

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

请求参数

URL 参数

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

request body 请求体

数据集字段结构说明

返回对象的格式说明

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

删除 {id} 数据集的 {fieldName} 字段

请求URL

DELETE /api/apps/${appId}/datasets/{datasetId}/fields?fieldName= HTTP/1.1
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

指标版本历史

原子指标（category=metric）和业务指标（category=measure）的定义保存后可主动查询版本历史。普通指标列表、详情及写入响应不会附带历史数据。

• 所有现有指标定义写入接口的请求体可选传顶层 changeReason（版本说明），用于记录本次创建背景或变更原因。它不必填，未传、null 或空字符串会把本次当前定义的版本说明保存为 null；服务端不校验长度。每次成功保存已有指标定义都会归档旧版并生成新版本，包括内容相同、重复提交或仅修改版本说明；校验、归档或主表更新失败时不生成新版本。独立默认预览图更新不属于定义保存，不生成版本。
• 当前定义存于 dataset_field；当前版号为该指标历史最大版号加一。每次成功保存时，历史按后端配置 N（默认 10，最小 2）保留 V1 和最近 N-1 条旧版。被清理的中间版号不重排或复用。
• 调低 N 后，该指标在下次成功保存时按新上限裁剪；未编辑的指标保留已有历史。版本查询返回实际保留的记录，不触发清理，也不定时扫描历史表。
• 历史项由归档时加工后的指标 DTO 快照还原，保留公式内部结构和显示值、格式、维度及粒度；读取时不按当前 schema 重写，也不使用当前标题覆盖。用户资料不写入快照，查询历史时按用户 ID 获取最新资料。

分组保存沿用原有 tags 更新接口，只更新 tags 并保留当前版本说明；更新前的旧记录仍会归档。该接口不接收 changeReason，不执行上述定义保存接口的说明清空规则。

指标、数据集或应用被物理清理时，相关全部历史（含 V1）由对应删除流程在同一事务中清理；逻辑删除、下线或移除主题域引用不清理历史。

查询数据集中的单个指标历史

GET /api/apps/{appId}/datasets/{datasetId}/indicator-versions?category=metric&fieldName=c1 HTTP/1.1

category 只能是 metric 或 measure，且必须和当前指标类别匹配；接口不支持数组、批量或省略指标标识的查询。权限与数据集指标读取相同。历史与指标定义存于同一 schema；租户查看平台指标时返回成功响应，data={items:[]}，不读取平台指标定义或历史，也不返回版号、保留配置及更新者资料。平台方查看自身指标、租户查看自有指标时正常返回历史。

data 的结构如下：

字段	类型	说明
currentVersion	LONG	当前主表定义展示的版本号
historyLimit	INTEGER	后端实际采用的历史保留上限
historyTruncated	BOOLEAN	保留历史数量少于 currentVersion - 1 时为 true
items	DatasetFieldDto[]	当前版加全部保留旧版，按 versionNo 倒序；每项是完整定义 DTO

每项额外包含 versionNo 和可空的版本说明 changeReason。versionNo=1 即记录起点；历史项的 appTitle、datasetTitle 来自各自快照，保持归档时的内容。历史更新者 ID 保存在快照的 updatedBy 中；查询时按该 ID 为 updater 补充最新的 id、name、loginName、email 和 avatar，用户不存在时为空，已有快照中的旧更新者资料不用于展示。历史接口不查询或补充 creator 信息。

请求参数

URL 参数

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

返回对象的格式说明

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

数据集指标

数据集指标说明

数据集指标定义

数据集指标是预定义的图表度量值，可以是数字常量值或者聚合计算的值。

数据集指标结构说明

指标的基础结构和字段结构相同，下面是指标特有的结构说明。

字段	类型	描述
expr.isAggregate	BOOL	指标是不是聚合计算的值
expr.isConstant	BOOL	指标是不是常量值

数据集指标接口说明

新增指标

请求URL

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

请求参数

URL 参数

字段	类型	是否必须	说明
appId	INTEGER	是	数据集所在的应用 ID
datasetId	INTEGER	是	数据集 ID

Request Body 参数

见数据集字段结构说明

返回对象的格式说明

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

接口示例1: 新增指标

Request

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

// Request Body:
{
    "label": "指标1",
    "visible": true,
    "expr": {
        "kind": "formula",
        "op": "sum({{1text}}.{region_id})",
        "value": "sum({{1text}}.{region_id})"
    }
}

Response

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

{
    "version": "version@9a5e106#6730f0d",
    "code": 0,
    "msg": "success",
    "data": {
        "fieldName": "c5",
        "label": "指标1",
        "expr": {
            "kind": "formula",
            "op": "sum({{1}}.{region_id})",
            "type": "number",
            "value": "sum({{1text}}.{region_id})",
            "isAggregate": true,
            "isConstant": false
        },
        "type": "number",
        "datasetId": 1,
        "appId": 1
    }
}

获取数据集所有指标

请求URL

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

请求参数

URL 参数

字段	类型	是否必须	说明
appId	INTEGER	是	数据集所在的应用 ID
datasetId	INTEGER	是	数据集 ID

返回对象的格式说明

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

修改数据集上的单个指标

请求URL

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

请求参数

URL 参数

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

response body 请求体

见数据集字段结构说明

返回对象的格式说明

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

接口示例1: 修改数据集上的单个指标

PUT /api/apps/1/datasets/1/metrics/c0 HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
    "label": "指标2",
    "visible": true,
    "type": "number",
    "originType": "number",
    "expr": {
        "kind": "formula",
        "op": "count({{1text}}.{country_id}) / sum({{1text}}.{region_id})",
        "value": "count({{1text}}.{country_id}) / sum({{1text}}.{region_id})"
    }
}

获取数据集上的单个指标

请求URL

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

请求参数

URL 参数

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

返回对象的格式说明

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

删除 {id} 数据集的 {fieldName} 指标

请求URL

DELETE /api/apps/${appId}/datasets/{datasetId}/metrics?fieldName= HTTP/1.1
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

URL 参数

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

返回对象的格式说明

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