数据集基本类型和格式规范

本页内容

三种数据集格式 #

数说方舟当前的页面组件，都可以用三种格式来描述其数据集。

  • aggregation
  • list
  • graph

1、最常见的“aggregation”类型 #

一般而言，统计类图表，如柱状图、饼/环状图、折线图、雷达图、旭日图、词云图、散点图、基本数据集类型等常见的表示“对比”、“分布”、“趋势”的数据可视化组件，使用aggregation类型的数据。此外，下拉列表、多选框、单选框等表示“选项”的组件，也使用aggregation类型数据。

aggregation格式的特点是可以表格形式呈现，且数据分为索引部分和数值部分，且通过接口一次性返回，不分页。

1.aggregation类型的数据集

如上图，这是一种最常见的aggregation数据集格式，它的数据集有一个索引列，来确保每一行都表现唯一的实体。非索引的部分是数值类型，可用于可视化为条形图的长度，或饼状图中对应的扇形的角度等。

aggregation的JSON格式示例如下：

{
    "data" : [ 
        [ "品牌", "声量" ], 
        [ "荣耀", 209399 ], 
        [ "华为", 180788 ], 
        [ "小米", 159856 ], 
        [ "苹果", 135052 ]
    ],
    "headerCols" : 1,
    "headerRows" : 1
}

它用data表示了一个二维表格，表格的最上面一行是索引（"headerCols" : 1）, 表格的最左边一列是索引（"headerRows" : 1）

2、带分页的“list”类型 #

顾名思义，list类型就是列表。列表不要求每一行都有明确的索引，也不限制数据的类型，但是list类型的数据需要满足分页的业务需要。

因此list类型的数据格式适合用于明细列表、原文展示、订单列表、视频列表、主播榜单等带有分页的，值类型较为丰富的组件场景。

2.list类型的数据集

上图所示是一种常见的list数据集应用场景，它支持分页加载数据，也支持数组类型和文本类型等多种值类型。同时，由于每次前端只加载一部分数据，所以它支持动态的服务端排序。

list数据格式的JSON示例如下：

{
    "total" : 110997,
    "pageSize" : 10,
    "currentPage" : 1,
    "list" : [
        {
            "学校" : [ null ],
            "出生日期" : "",
            "是否广告" : "否",
            "源内容" : "#畅轻青春环游记#wuli代言人@王凯kkw 闪亮登场！！！连续笑容暴击，承包今日份的甜蜜~ http://t.cn/E6kid7t ​"
        }, {
            "学校" : "",
            "出生日期" : "",
            "是否广告" : "否",
            "源内容" : "大雾重重 时代喧哗造物忙 火光忷忷 指引盗寇入太行"
        }, {
            "学校" : [ null ],
            "出生日期" : "",
            "是否广告" : "否",
            "源内容" : "#王凯[超话]# #王凯青春环游记# 前方传来了无法复制的“盒盒盒盒盒”[doge]没错，今天也是为@王凯kkw 着魔的一天[污]http://t.cn/EozkvCO ​"
        }, {
            "学校" : [ null ],
            "出生日期" : "",
            "是否广告" : "否",
            "源内容" : "自然赠予你，树冠 微风 肩头的暴雨，片刻后生成，平衡 忠诚 不息的身体"
        }, {
            "学校" : "",
            "出生日期" : "",
            "是否广告" : "否",
            "源内容" : "#记录王凯[超话]##王凯慢游芬兰# 把你的心 我的心串一串串一株幸运草 串一个同心圆你的心，我的心……[给你小心心]@王凯kkw 记录王凯 慢游芬兰宣传图原图去字壁纸9p ​"
        }
    ]
}

3、表示关系的“graph”类型 #

一个完整的“graph”类型数据集可以同时表示实体、实体的类型与实体之间的关系，是一种较为复杂的数据集类型。它由节点、类型、关系三个子数据集构成。

3.关系图示例

在数据集中，分别用nodes表、type表和edges表来表示节点、类型和关系。每一个node有一个唯一ID，三个表之间用此ID来关联。

数据集的访问和格式规范 #

一般，服务端通过http协议提供数据集给web前端，在数说方舟，我们同样可以通过新建自定义脚本，生成API接口链接，服务复杂的数据需求。数说方舟也明确了前后端之间对接口返回的数据集格式规范。如果你是一个开发者，那么这些规范你一定要了解。

客户端发起数据集请求 #

每一个数据集，都需要提供一个唯一的URL. 客户端通过此URL可以访问到数据集。

小练习

在命令行终端执行下面的curl命令，观察返回的数据集
（小伙伴可以通过powershell或者postman练习）

curl 'https://matrix.datastory.com.cn/serv/v2/api/3RS3/books/helloworld'

或在浏览器地址栏中访问下面的地址，观察返回的数据集

https://matrix.datastory.com.cn/serv/v2/api/3RS3/books/helloworld

如果一切正常，那么你将会得到一个JSON格式的返回，其中dataset字段中包含了一份“aggregation”类型的数据集。

此外，客户端可以根据需求动态传递(POST)参数给数据集接口，例如通过filters参数动态调整筛选条件，通过openStrategy参数选择是否接受缓存等。

小练习

命令行终端执行下面的命令，观察在有参数提交时数据接口的返回。

curl 'https://matrix.datastory.com.cn/serv/v2/api/3RS3/books/helloworld' \
 -H 'Content-Type: application/json' \
 --data-binary '{"filters":{"是否广告":["否"]},"openStrategy":false}'

需要注意的是，若数据集接口需要根据参数进行返回，那么服务端需提供这些参数的缺省值。即确保客户端总是能只通过URL就可以获得默认数据。这一点很重要。

服务端按照规范格式返回数据集 #

在上文中，你已经通过请求看到了服务端返回，其返回的数据将总是满足如下格式规范

Response Header
├── X-Matrix-IsCache
├── X-Matrix-TookTime
├── X-Matrix-Type
├── X-Matrix-Version
├── X-Matrix-Url
└── X-Matrix-Name

Response
├── code
├── data
│   ├── meta
│   │   ├── datasetType
│   │   ├── parameters
│   │   ├── dimensions
│   │   ├── measures
│   │   └── fieldsInfo
│   └── dataset
├── message
└── success

其中Response Header部分完全是由方舟自动生成的，Response部分可以通过方舟分析表发布生成，也可以通过在方舟编写脚本来生成，或者代理外部API服务。

我们在下一章节会根据场景来描述Response各个值的意义。本章先对Response Header的参数分别做下解释：

Response Header部分详解：

参数 描述
X-Matrix-IsCache 当前接口response数据是否是缓存数据，有两个值true和false
X-Matrix-TookTime 当前接口返回所经历时间，单位秒
X-Matrix-Type 当前接口通过何种方式发布生成，分别有透视 表(pivot)，筛选表(display)，Nashorn JS脚本(nashorn)，服务治理(openapi)四种
X-Matrix-Version 接口版本，用于前端判断接口的解析方式，当前最新版本号是2
X-Matrix-Url 通过方舟暴露的URL地址，是相对地址，不包含域名部分
X-Matrix-Name 数据集接口的名称，对应到方舟的分析表名，或脚本名称

Response部分详解：

字段 描述
code 统一返回码
data 接口返回的数据和数据元信息
data.meta 元信息，用于决定数据集的渲染方式以及联动行为
data.meta.datasetType 接口格式类型，分别有透视分析格式(aggregation)，数据筛选格式(display)，列表格式(list)，关系图(graph)
data.meta.parameters 接口可以接受的参数列表
data.meta.dimensions dataset中的维度(用于判断可以向外传递什么样的联动变量)
data.meta.measures 当前指标是什么，datasetType为透视分析格式的时候需要
data.meta.fieldsInfo 参数、维度的对应的字段，以及display所选的展示字段的字段信息
data.dataset 数据集，用于渲染图表
message 接口信息，一般用于服务报错信息
success 接口是否成功返回

关于fieldsInfo

fieldsInfo包含以下信息：

  • fieldName 字段名，指的是底层存储的字段真名
  • fieldAlias 字段别名
  • fieldIsNested 字段是否是嵌套字段
  • fieldIsArray 字段是否是数组字段
  • fieldIsAnalyzed 字段是否带有分词器
  • fieldType 字段类型
  • dateFormat 注意这个是API v2新增加的 时间类型字段的格式