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 |
用户编辑的字段描述,默认为空 |
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 |
返回对象的格式说明
字段 |
类型 |
说明 |
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 |