5.1. 定义数据集

点击数据集管理页面的【添加】按钮，即可添加数据集。 目前支持的数据集类型包括：SQL、CSV、CSV文件、Excel、HTTP接口、JSON、JSON文件。

对于CSV文件、Excel、JSON文件数据集，除了上传文件外，也可选择使用服务器端文件，且只能在管理员授权允许的目录内选择。 使用管理员账号登录后，点击右上角设置图标按钮中的【管理数据集资源目录】菜单，添加一个服务端目录项，然后将其分享给指定用户， 目标用户即可新建使用此服务端目录内文件的数据集。

数据集属性

数据集属性描述数据集的数据结构，在后续定义图表时，即是通过为数据集属性绑定数据标记，来实现将数据映射至图表的。
数据集属性通常无需用户定义，在执行必须的【预览】操作后，系统会自动解析和生成它们。

数据集参数

对于SQL、CSV、CSV文件（服务器端）、Excel（服务器端）、HTTP接口、JSON、JSON文件（服务器端）数据集，用户可以编辑【参数】，添加了参数的数据集称为参数化数据集。 参数化数据集可输入与参数关联的参数化语句， 当关联了参数化数据集的图表在展示时，用户可自由定义其参数值，从而展示用户需求数据的图表。

例如，对于如下参数：

名称    类型    必填
value   数值    是

SQL数据集的SQL查询语句可以为：

SELECT NAME, VALUE FROM T_ANALYSIS WHERE VALUE = ${value}

CSV数据集的CSV文本可以为：

name,   value
aa,     ${value}
bb,     14

CSV文件（服务器端）数据集的目录内文件名可以为：

file-${value}.csv

Excel（服务器端）数据集的目录内文件名可以为：

file-${value}.xlsx

HTTP接口数据集的请求地址可以为：

http://aaa.com/api?param=${value}

HTTP接口数据集的请求体JSON可以为：

[
  { name: 'param', value: ${value} }
]

HTTP接口数据集的请求头JSON可以为：

[
  { name: 'header0', value: ${value} }
]

JSON数据集的JSON文本可以为：

[
  { name: 'aa', value: ${value} },
  { name: 'bb', value: 14 }
]

JSON文件（服务器端）数据集的目录内文件名可以为：

file-${value}.json

参数化数据集在执行预览时，会弹出参数值输入框，用户输入了参数值后，才会执行预览。

例如，对于上述参数示例，在输入了value的值为16后， SQL数据集将会执行如下SQL查询语句：

SELECT NAME, VALUE FROM T_ANALYSIS WHERE VALUE = 16

选中编辑区的参数名后执行添加参数操作，可自动设置参数名。

参数化语句语法

插值：
${参数名}

条件判断：
<#if 条件></#if>
<#if 条件>…<#else>…</#if>
<#if 条件>…<#elseif 条件>…<#else>…</#if>

数组、集合遍历：
<#list 参数名 as item>…${item}…</#list>
<#list 参数名 as item>…${item}…<#sep>元素间要插入的分隔内容</#list>

条件：

• 参数名??
  当用户填写参数名对应的值时为true， 否则为false，可用于处理非必填参数。
• 参数名
  布尔参数值为true时。
• !参数名
  布尔参数值为false时。
• 参数名 == “…”、 参数名 != “…”
  字符串参数值等于、不等于。
• 参数名 == …、 参数名 != …、 参数名 gt …、 参数名 gte …、 参数名 lt …、 参数名 lte …
  数值参数值等于、不等于、大于、大于等于、小于、小于等于。
• 条件1 || 条件2、 条件1 && 条件2、 !条件
  条件组合：或、与、非。

示例：

SELECT NAME, VALUE FROM T_ANALYSIS
WHERE NAME = '${name}'
<#if 最小值??>
AND VALUE >= ${最小值}
<#else>
AND VALUE IS NOT NULL
</#if>
<#if 名称集合??>
AND NAME IN
(
  <#list 名称集合 as item> '${item}' <#sep>,</#list>
)
</#if>
<#if ascByName>
ORDER BY NAME ASC
</#if>
<#if limitCount??>
limit 0, ${limitCount}
</#if>

对应上述示例的数据集参数为：

参数化语句的解析底层采用了Freemarker，详细语法请参考其官方文档。

设置参数输入框类型

在定义数据集参数时，可选设置参数输入框类型（默认为文本框），当图表展示时，数据集参数设置面板将被绘制为指定类型的输入框。

系统目前支持的输入框类型为：文本框、下拉框、日期、时间、日期时间、单选框、复选框、文本域，详细设置如下表所示：

[ 待选项名值对象, … ]

{ multiple: true, options: [ 待选项名值对象, … ] }

{ format: ‘…’ }

{ format: ‘Y-m-d’ }

{ format: ‘…’ }

{ format: ‘H:i:s’ }

{ format: ‘…’ }

{ format: ‘Y-m-d H:i:s’ }

[ 待选项名值对象, … ]

[ 待选项名值对象, … ]

其中，日期格式各符号说明如下表所示：