1. 数据集字段

1.1. 数据集字段说明

1.1.1. 数据集字段定义

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

数据集字段结构说明

字段 类型 描述
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有，不能编辑
userComment STRING 用户编辑的字段描述，默认为空
inUse BOOL 标记这个字段是否被使用

1.2. 接口说明

1.2.1. 新增字段

请求URL

POST /api/v1/apps/${appId}/datasets/{datasetId}/fields"

需要认证：是

请求参数

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

见数据集字段结构说明

返回对象的格式说明

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

接口示例1: 新增字段

POST /api/v1/apps/1/datasets/1/fields

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

返回

{
    "version": "3.2-SNAPSHOT@35b7de5#cf5cbbe",
    "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}"
    }
}

1.2.2. 获取数据集所有字段

请求URL

GET /api/v1/apps/${appId}/datasets/{datasetId}/fields"

需要认证：是

请求参数

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

返回对象的格式说明

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

1.2.3. 批量更新数据集的字段

请求URL

PUT /api/v1/apps/${appId}/datasets/{datasetId}/fields"

需要认证：是

请求参数

URL 参数
字段 类型 是否必须 说明
appId INTEGER 是 数据集所在的应用 ID
datasetId INTEGER 是 数据集 ID
response body 请求体

多字段的配置信息

返回对象的格式说明

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

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

PUT /api/v1/apps/1/datasets/1/fields

{
    "options": {
        "schema": [
            {
                "datasetId": "1",
                "fieldName": "id",
                "hsVersion": 6,
                "originType": "integer",
                "type": "number",
                "comment": "序号",
                "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",
                "comment": "省份代码",
                "config": {
                    "seperator": " ",
                    "dialectName": "EngineDialect"
                },
                "label": "province_code",
                "basicType": "string",
                "visible": true,
                "nativeType": "varchar",
                "suggestedTypes": [
                    "number",
                    "string"
                ],
                "detectedType": "number",
                "defaultAggrType": "count"
            }
        ]
    },
    "hsVersion": 13
}

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

请求URL

GET /api/v1/apps/${appId}/datasets/{datasetId}/fields/{fieldName}"

需要认证：是

请求参数

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

返回对象的格式说明

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

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

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

请求URL

PUT /api/v1/apps/${appId}/datasets/{datasetId}/fields/{fieldName}"

需要认证：是

请求参数

URL 参数
字段 类型 是否必须 说明
appId INTEGER 是 数据集所在的应用 ID
datasetId INTEGER 是 数据集 ID
fieldName STRING 是 字段名
request body 请求体

数据集字段结构说明

返回对象的格式说明

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

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

请求URL

DELETE /api/v1/apps/${appId}/datasets/{datasetId}/fields/{fieldName}"

需要认证：是

请求参数

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

返回对象的格式说明

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

2. 数据集指标

2.1. 数据集指标说明

2.1.1. 数据集指标定义

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

数据集指标结构说明

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

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

2.2. 接口说明

2.2.1. 新增指标

请求URL

POST /api/v1/apps/${appId}/datasets/{datasetId}/metrics"

需要认证：是

请求参数

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

见数据集字段结构说明

返回对象的格式说明

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

接口示例1: 新增指标

POST /api/v1/apps/1/datasets/1/metrics

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

返回

{
    "version": "3.2-SNAPSHOT@@git.commit.id.abbrev@#null",
    "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
    }
}

2.2.2. 获取数据集所有指标

请求URL

GET /api/v1/apps/${appId}/datasets/{datasetId}/metrics"

需要认证：是

请求参数

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

返回对象的格式说明

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

2.2.3. 修改数据集上的单个指标

请求URL

PUT /api/v1/apps/${appId}/datasets/{datasetId}/metrics/{fieldName}"

需要认证：是

请求参数

URL 参数
字段 类型 是否必须 说明
appId INTEGER 是 数据集所在的应用 ID
datasetId INTEGER 是 数据集 ID
fieldName INTEGER 是 指标名
response body 请求体

见数据集字段结构说明

返回对象的格式说明

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

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

PUT /api/v1/apps/1/datasets/1/metrics/c0

{
    "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})"
    }
}

2.2.4. 获取数据集上的单个指标

请求URL

GET /api/v1/apps/${appId}/datasets/{datasetId}/metrics/{fieldName}"

需要认证：是

请求参数

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

返回对象的格式说明

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

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

请求URL

DELETE /api/v1/apps/${appId}/datasets/{datasetId}/metrics/{fieldName}"

需要认证：是

请求参数

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

返回对象的格式说明

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

results matching ""

    No results matching ""

    数据集 从表数据集

    衡石文档