YaoDocs分析图表
分析图表(Chart) 主要用于编排数据统计分析查询逻辑，支持使用 JavaScript 脚本处理各查询节点结果，可在数据管理后台直接查阅分析图表，亦可作为处理器 (process) 来使用，引用方式为 charts.<分析图表名称>。分析图表(Chart)支持基于 ElasticSearch 、MySQL 实现的数据分析引擎用于各种业务场景。
数据看板、数据大屏页面亦可采用同样方式编写。
1 命名规范
分析图表描述文件是以 小写英文字母 + .chart.json 扩展名命名的 JSON 文本文件, <name>.chart.json; 结果处理脚本文件是以 分析图表名称 + . + 脚本名称 + .js 扩展名，命名的 JavaScript 脚本文件 <name>.<script>.js 。
数据看板扩展名为 .kan.json, 数据大屏扩展名为 .scr.json
| 文件夹 (相对分析图表根目录) | 文件名 | 分析图表名称 | 脚本名称 | Process (在 API /Flow 中引用) | API 路由地址 |
|---|---|---|---|---|---|
| / | name.chart.json | name | charts.name | /api/xiang/chart/name/查询接口 | |
| / | name.count.js | name | count | - | - |
| /group | name.chart.json | group.name | charts.group.name | /api/xiang/chart/group.name/查询接口 | |
| /group | name.count.js | gorup.name | count | - | - |
| /group1/group2 | name.chart.json | group1.group2.name | charts.group1.group2.name | /api/xiang/chart/group1.group2.name/查询接口 | |
| /group1/group2 | name.count.js | group1.group2.name | count | - | - |
2 文档结构
分析图表编排文档由基础信息、查询节点、输出数据和分析页面渲染参数构成。 查看完整示例
json
{
"lang": "gou",
"label": "最新信息",
"version": "1.0.0",
"description": "最新信息",
"nodes": [],
"output": {},
"apis": {},
"filters": {},
"page": {}
}
| 字段 | 类型 | 说明 | 必填项 |
|---|---|---|---|
| lang | String | 数据查询条件描述语言。 许可值 gou 适用基于数据库实现的数据分析引擎。tai 适用基于 ElasticSearch 实现的分析引擎(单独挂载)。 默认值为gou | 是 |
| label | String | 分析图表呈现名称，用于开发平台呈现 | 是 |
| version | String | 版本号，用于依赖关系校验和开发平台呈现 | 是 |
| description | String | 分析图表介绍，用于开发平台呈现 | 否 |
| nodes | Array<Object Node> | 查询节点 | 是 |
| output | Object | String | 输出结果定义, 同业务逻辑编排(flow) output | 是 |
| apis | [key:String]:Object API | 分析图表查询 API， 可通过设置同 key 设置关闭接口、设置鉴权方式和默认值选项。 | 否 |
| filters | [key:String]:Object Filter | 查询过滤器设置。 同数据表格(talbe) fliters。 | 否 |
| page | Object Page | 分析图表查询页设置。 | 是 |
2.1 查询节点 nodes
json
{
"nodes": [
{
"name": "行业分布",
"query": {
"model": "service",
"select": ["city", ":COUNT(id) as cnt", "@industries.$ as industry"],
"wheres": [
{ "column": "created_at", "value": "{{$query.from}}", "op": "ge" },
{ "column": "created_at", "value": "{{$query.to}}", "op": "le" }
],
"order": ["cnt.desc"],
"limit": 100,
"group": ["@industries.$", "city"]
}
},
{
"name": "计费方式",
"query": {
"model": "service",
"select": ["city", ":COUNT(id) as cnt", "@price_options.$ as option"],
"wheres": [
{ "column": "created_at", "value": "{{$query.from}}", "op": "ge" },
{ "column": "created_at", "value": "{{$query.to}}", "op": "le" }
],
"order": ["cnt.desc"],
"limit": 100,
"group": ["@price_options.$", "city"]
}
},
{
"name": "合并结果",
"process": "xiang.chart.MergeData",
"args": [
["城市", "行业", "计费"],
{
"行业": { "key": "city", "values": "{{$res.行业分布[*].industry}}" },
"计费": { "key": "city", "values": "{{$res.计费方式[*].option}}" }
}
]
}
]
}
一个分析图表查询编排(Chart)可以有多个查询节点, 每个查询节点，也写设置对应数据引擎的 query 查询参数， 也可以调用一个处理器(process), 可以指定结果处理脚本和返回值，在查询节点用可以引用上下文信息。上下文数据引用、结果处理脚本具体与与业务逻辑编排(Flow)一致.
Object Node 数据结构
| 字段 | 类型 | 说明 | 必填项 |
|---|---|---|---|
| name | String | 查询节点名称 | 是 |
| query | Query DSL | 查询语言 查看完整说明 | 否 |
| process | String | 调用处理器 process query 与 process 任选其一。 如同时存在忽略 process 设置。 | 否 |
| args | Array<Any> | 处理器参数表.可以引用输入输出或上下文数据，与 flow 相同。 查看完整说明 | 否 |
| script | String | 结果处理脚本，支持 ES5，与 flow 相同。 查看完整说明 | 否 |
| outs | Array<String> | 查询节点结果输出.使用 flow 相同。如不设置，返回值等于处理器返回结果。 查看完整说明 | 否 |
| next | Object Next | 当查询结果符合设定条件时跳转至指定查询节点(尚未实现) | 否 |
数据分析查询语法 Query DSL
| 数据分析引擎 | 说明 |
|---|---|
gou | Gou Query DSL(Domain Specific Language) 用来描述数据查询条件，适用基于数据库实现的数据分析引擎。 |
tai | Tai Query DSL(Domain Specific Language) 用来描述数据查询条件，适用基于 ElasticSearch 的数据分析引擎。 |
2.2 查询页 page
json
{
"page": {
"primary": "城市",
"layout": {
"filters": [
{ "name": "开始时间", "width": 6 },
{ "name": "结束时间", "width": 6 }
],
"charts": [
{ "type": "line", "props": {} },
{ "type": "bar", "props": {} }
]
}
}
}
布局 (layout)
| 字段 | 类型 | 说明 |
|---|---|---|
charts | Array<Object Render | String > | 可使用的图表组件 |
filters | Array<Object FilterInstance | String > | 可呈现的查询过滤器 |
Object FilterInstance 数据结构
| 字段 | 类型 | 说明 | 必填项 |
|---|---|---|---|
| name | String | 字段名称。必须已在查询过滤器方式(filters)中定义。 | 是 |
| width | Integer | 列宽度。使用栅格系统，有效值 1-24。默认值为 6 | 否 |
2.3 分析图表查询接口 apis
分析图表默认开启数据和配置查询接口， 可通过设置同 key 设置关闭接口、设置鉴权方式和默认值选项。
json
{
"apis": {
"data": {
"disable": true,
"guard": "bearer-jwt",
"default": {}
},
"setting": {
"guard": "-",
"default": {}
}
}
}
| 字段 | 类型 | 说明 | 必填项 |
|---|---|---|---|
| disable | Bool | 关闭接口。 true 关闭接口 | 否 |
| guard | String | 接口鉴权中间件, 多个用 , 分割， 设置为 - 不设置鉴权中间件, 不设置继承默认鉴权方式。 | 否 |
| default | Object | 参数表默认值, {"from":"2021-08-28"} | 否 |
接口列表
管理接口(key) | 请求方式 | 路由(相对) | 说明 |
|---|---|---|---|
| data | GET | /data | 返回查询结果 查看完整说明 |
| setting | GET | /setting | 读取分析图表配置信息, 用于前端界面渲染 查看完整说明 |
3 完整示例
完整示例保存在 examples 目录，查看完整示例
json
{
"lang": "gou",
"label": "指标对比",
"version": "1.0.0",
"decription": "指标对比",
"nodes": [
{
"name": "行业分布",
"process": "models.service.get",
"query": {
"select": ["city", ":COUNT(id) as cnt", "@industries.$ as industry"],
"wheres": [
{ "column": "created_at", "value": "{{$query.from}}", "op": "ge" },
{ "column": "created_at", "value": "{{$query.to}}", "op": "le" }
],
"order": ["cnt.desc"],
"limit": 100,
"group": ["@industries.$", "city"]
}
},
{
"name": "计费方式",
"process": "models.service.get",
"query": {
"select": ["city", ":COUNT(id) as cnt", "@price_options.$ as option"],
"wheres": [
{ "column": "created_at", "value": "{{$query.from}}", "op": "ge" },
{ "column": "created_at", "value": "{{$query.to}}", "op": "le" }
],
"order": ["cnt.desc"],
"limit": 100,
"group": ["@price_options.$", "city"]
}
},
{
"name": "合并结果",
"process": "xiang.chart.MergeData",
"args": [
["城市", "行业", "计费"],
{
"行业": { "key": "city", "values": "{{$res.行业分布[*].industry}}" },
"计费": { "key": "city", "values": "{{$res.计费方式[*].option}}" }
}
]
}
],
"output": "{{$res.合并结果}}",
"apis": {
"data": {
"guard": "-"
},
"setting": {
"guard": "-"
}
},
"filters": {},
"page": {
"primary": "城市",
"layout": {
"filters": [
{ "name": "开始时间", "width": 6 },
{ "name": "结束时间", "width": 6 }
],
"charts": [
{ "type": "line", "props": {} },
{ "type": "bar", "props": {} }
]
}
}
}