1. 第一章概述

寄云时序数据库系统是为工业领域时序数据的接入，存储，查询，展示和管理而设计开发的时序数据库系统。它和传统的关系型数据库系统，或者目前流行的NoSQL的数据库系统相比有独特的特点。

寄云时序数据库系统管理的是结构清晰的时序数据，在数据导入，数据存储和查询的环节，针对时序数据的特点做了相应的优化处理，因此能够支持单机每秒万点以上的实时注入，和秒级查询延迟。

寄云时序数据库系统提供基于Web页面的图形化用户交互界面，用户通过可视化界面方便快捷的完成数据导入，数据查询，和数据可视化等操作。

寄云时序数据库系统提供对时序数据SQL风格的查询。

2. 第二章时序数据基本概念

时序数据特点

在工业领域，生产、测试、运行阶段都可能会产生大量带有时间戳的传感器数据，属于典型的时间序列数据。时间序列数据主要由各类型实时监测、检查与分析设备所采集或产生，涉及制造、电力、化工、工程作业等。以下是一个典型的时序数据的例子：

该数据由三部分组成:

时间戳: 对应__time字段，它是所有时序数据必有的字段，所有查询也都以时间为中心，比如指定时间段、时间粒度等进行查询。

维度列: 维度列是描述对应时点事件的维度信息，通常用于筛选过滤数据。维度列的值是可枚举，以字符串或整型存储，如示例数据中的mid、ConState、HmiPowLimit。

度量列: 度量列是用于聚合和计算的列。在我们的例子中，除了时间戳字段(__time)和三个维度列其他都是度量列。度量列通常是数值型，并且包含支持count、sum、mean等计算操作。

此类数据的典型特性决定了其存取方面的特定需求，而这些需求传统的关系型数据库支持比较差，具体如下表所示：

数据特点	存取需求特点	传统关系数据库支持情况
数据形态单一	数据关系性弱，多是超大的单表形态	关系数据库的优势在于“关系”，在单一超大表上无优势，且通常需要使用额外的分库分表方案解决，引入大量额外工作量
包含时间戳信息	大部分查询是在时间戳上有多种不同时间粒度/不同时间跨度的聚合操作	并无原生的时间粒度支持，可通过udf操作实现或是额外人为加入一系列索引，但查询效率低且维护代价高
数据产生频度高	数据快速持续实时产生，增长速度快	缺省压缩比低，通常需要特别设置压缩级别，而压缩本身会明显影响关系数据库的查询性能
	需要实时/近实时加载并提供实时查询	对于实时写入并即时查询支持差，大部分数据库存在写锁控制
不同传感器数据产生频度不一	呈现“超宽表”的模式且模式不稳定，会随传感器本身或是IGW采集配置等等的调整而变化	数据模式（schema）相对稳定，动态修改支持差
数据项成百上千且随传感器部署调整而变化

由上表可见，传统的关系型数据库无法方便高效地处理此类数据从加载、存储到查询的多方面需求。为了更好的处理时间序列数据，寄云基于开源产品二次开发了专门管理时间序列数据的专业化产品套件——寄云时序数据库。不同于传统关系型数据库，时序数据库在数据摄入、存储、索引、查询等方面都进行了特定的优化，从而达到更优的数据加载、数据压缩、查询性能，适用于工业传感器数据的应用分析场景。

3. 第三章订阅tsdb

3.1. tsdb版本：

当前订阅的tsdb服务的版本：V1.0

3.2. 订阅及使用说明：

1.参考寄云应用开发与数据分析平台使用手册完成tsdb服务的订阅，订阅过程中，可以输入tsdb服务的服务名称。

3.3. tsdb服务详情

订阅完成后，在服务详情页面将给出如下服务参数：

用户名	unLHB8j3Q
密码	***************************************
数据源前缀	unLHB8j3Q_

寄云应用开发与数据分析平台能够提供应用绑定服务的能力，在完成绑定后，将把服务相关的环境变量注入到应用实例中去（绑定的详细操作过程，请参见使用手册），在应用开发的过程中，直接使用这些环境变量即可实现对tsdb服务的访问和操作。

绑定后注入应用的环境变量包括：

变量名称	描述
TSDEMO_TSDB_PREFIX	Tsdb数据源前缀
VCAP_SERVICES	Tsdb访问参数
TSDEMO_TSDB_USER	Tsdb用户名
TSDEMO_TSDB_PASSWORD	Tsdb密码

3.4. tsdb服务使用

创建好的tsdb点击“管理服务”即可通过网页浏览器方式访问。默认的访问地址是：http://tsdb.neuseer.com:8089/login/

首先见到的是登陆页面，登录的用户名，密码为创建tsdb服务基本信息中的用户名和密码如：

登录后页面如下，显示“数据源配置”“图表”“我的仪表盘”“时序数据加载”“时序数据查询”：

4. 第四章数据加载

4.1. 数据加载

寄云时序数据库提供两种数据加载方式:实时数据加载和批量加载。

4.1.1. 实时加载：

寄云TSDB支持HTTP或者MQTT协议的数据实时导入。

如需实时导入HTTP数据，须按照部署说明书，部署响应实时导入组件。包括HTTP消息接收服务（Nginx），flume消息收集，和Kafka消息队列。并在配置文件中配置消息路径和消息格式等属性。目前仅支持Json格式的消息内容。

如需实时导入MQTT数据，需按照部署说明书，部署响应MQTT实时导入组件。包括MQTT消息服务（EMQ），和Kafka消息队列。并在配置文件中配置消息路径和消息格式等属性。目前仅支持Json格式的消息内容。

从HTTP或者MQTT协议进入时序数据库系统的实时数据，均通过Kafka消息队列中转。

用户须通过neuseer平台服务，订阅Kafka服务端，Kafka客户端用户可在本地创建，Kafka操作详细步骤请参考用户手册中的kafka服务使用说明

用户在配置好Kafka消息队列后，通过交互界面的“时序数据加载”菜单中的“实时数据加载”选项加载数据。通过配置参数列表生成加载配置文件。

具体的参数列表和解释见下表：

	描述	例子
加载类型	导入数据的方式	kafka
topic	Kafka服务详情中对应的Topic名称
Kafka地址：端口号	如果从多个kafka导入，用","分隔
实时加载的任务周期	实时加载任务提交后会在后台常驻，持续从消息队列中pull数据，每隔一段时间进行一次handoff，形成segment到深度存储中，该参数即用于配置handoff的周期。
是否从最早位置读取	如果是首次启动对某个topic数据到目标数据源的加载任务，需要将该参数设置为“是”，否则会丢弃掉在启动时点之前队列中的数据。
副本数	实时加载作业任务的副本数	1
目标数据源	导入到时序数据库中的数据源名称,类似于关系型数据库中数据表的名称，目标数据源命名为：数据源前缀+起的名称，数据源前缀在创建的tsdb服务基本信息中
时间分片粒度	segment的存储粒度,比如以day为创建粒度,那么就会一天创建一个segment	day, hour
数据格式	输入数据格式,目前支持Json/csv
数据列名	输入数据的所有列的名称，如果是csv文件列名要和数据的列数相等,如果是json文件要将一行所有的字段名称输入列名用逗号分隔,csv列名有序,json列名无序
维度列表	用来标识数据行各个类别信息
时间戳格式	时间戳格式默认为auto, 格式分为iso/millis/posix/auto
时间戳列名	指定时间戳为数据列名中的具体某一列
数据容错	如果为true,遇到数据异常则停止加载如果为false,将忽略错误数据继续加载
内存索引最大记录数	当内存中索引的记录数达到该配置时进行持久化（指在作业节点上的持久化）
单个分片最大记录数	同一个segment中当前分片中记录数达到该配置时则生产新的分片。
提交目标集群	下拉框选择数据的目标集群（在[数据源配置]->[时序数据库集群]中已配置集群）

实时加载的数据成功提交后，提示根据输入参数生成的Json格式的加载配置文件。

如下图所示。加载配置文件将以Post命令方式提交至目标时序数据库系统执行。在“数据源配置”菜单中点击“刷新时序元数据”，即可找到新添加的实时数据源。通过查询或者图表的方式探索数据源中的数据。

4.2. 批量加载

寄云时序数据库系统支持从Hadoop HDFS文件中批量加载数据。用户须通过Neuseer平台的服务目录中创建HDFS服务，具体操作请查看用户手册中“HDFS服务使用说明”。“时序数据加载”菜单中选择“批量数据加载”选项，可通过填写配置参数生成加载任务脚本。其中必填项前有红色“*”标记，如下图所示。

参数列表详细说明见下表：

名称	描述	例子
加载类型	导入数据的方式	Hdfs
输入路径	导入文件所在的hdfs路径,如有多个文件用逗号分隔hdfs://hdp-master/user/+创建的hdfs服务的基本信息中的用户名+文件名称
目标数据源	导入到时序数据库中的数据库源名称,类似于关系型数据库中数据表的名称。目标数据源命名为：数据源前缀+创建的名称，数据源前缀在创建的tsdb服务基本信息中
时间分片粒度	segment的存储粒度,比如以day为创建粒度,那么就会一天创建一个segment	day, hour
时间段	加载的数据的时间段,如果实际数据超出加载的时间段,在时间段以外的数据将不会被加载(请按实际数据时间范围填写)
数据格式	输入数据格式,目前支持Json/csv
数据列名	输入数据的所有列的名称，如果是csv文件列名要和数据的列数相等,如果是json文件要将一行所有的字段名称输入列名用逗号分隔,csv列名有序,json列名无序
维度列表	用来标识数据行各个类别信息
时间戳格式	时间戳格式默认为auto, 格式分为iso/millis/posix/auto
时间戳列名	指定时间戳为数据列名中的具体某一列
加载分区方式	提高批量加载时的并发度最多只可以设置分区数量和分区记录数中的一项。
内存索引最大记录数	当内存索引中记录数达到该配置数时进行持久化
容错开关	如果该开关关闭，则加载中遇到错误记录将抛出异常并退出，反之丢弃错误记录并继续任务
提交目标集群	下拉框选择数据的目标集群（在[数据源配置]->[时序数据库集群]中已配置集群）

4.3. 数据查询

寄云时序数据库系统支持时序数据的类SQL查询。

时序数据查询

时序数据查询具有选择集群、编辑并执行SQL、结果展示、结果文件导出、查询历史等功能。

选择数据集群

点击“时序数据查询”，在交互区左侧上部列表框中选择时序数据库集群，在下方的列表框中列出该集群中的数据源。在交互区右侧上部的编辑框中输入SQL语句，点击“执行SQL”按钮，在下方显示查询结果或者出错信息。

编辑并执行SQL

目前对时序数据的查询语句仅支持三类查询：show tables、describe和select单表查询。具体的语法细节请参照页面右上角“使用文档”。

结果展示与导出

如果正确返回查询结果，将在页面右下部分的结果区域内以表格的形式显示。否则显示错误信息。查询结果可导出为文件。在“执行SQL” 后，选择右侧的“结果导出到文件”按钮。可将查询结果导出到本地文件，文件格式可选Json、CSV等，如下图所示：

文件将通过网络下载方式保存至下载文件默认目录。文件名为 “db_YYYYMMDD_HHMMSS.XXX”。文件名后缀根据文件格式为.csv, .json或者.txt等。

查询历史记录

系统中保存历史查询记录，点击“历史记录”，列出按时间顺序倒排的历史查询记录。每条历史记录有SQL语句、提交时间点、执行耗时、执行状态，结果等属性。在每行记录的右侧有“执行SQL”按钮，可以直接执行历史记录。

4.4. 图表

创建图表有两种方法：在数据源列表页/数据表列表页中点击数据源名称/数据表名称直接进入图表页进行编辑；或是在图表列表页点击一个已经存在的图表进行编辑，通过saveAs的方式产生新的图表。

图表定制页分为两大区域，左侧的定制区和右侧的展示区。下图为定制区。定制区属性有数据源、时间、图表相关、过滤等分组。时序数据源和数据表的分组和组属性略有区别。

数据表图表需定义时间列，可定制SQL等属性组。

定制项说明：

组	名称	说明	例子	备注
数据源	Datasource	下拉列表框，列出可选的图表所关联的数据源，或者数据表名称。	Igw_data	右侧的“edit”链接到数据源的度量列编辑页。
	Visualization Type	下拉列表框，列出可选的图表类型。	Table View	默认是Table View
时间	Time Granularity	可编辑下拉列表框，列出图表展示时的时间粒度。从5秒钟到一个月。可以自己编辑时间粒度，如3 days。	5 seconds	(时序数据图表选项）查询结果中度量列将按照时间粒度做聚合操作。
	Origin	可编辑下拉列表框，用于定义划分时间粒度的起始点。如时间粒度定义为一周，Origin可以从一周的任意一天开始，如周一。	Monday	(时序数据图表选项）
	Time Column	可编辑下拉列表框，用于在关系表中选择时间列		(关系表图表选项）
	Time Grain	可编辑下拉列表框，用于定义关系表时间列上图表展示时的时间粒度。		(关系表图表选项）查询结果中度量列将按照时间粒度做聚合操作。
	Since，Until	可编辑下拉列表框，用于过滤时间的起始和结束点。可以自己编辑时间点，如 5 years ago.	Since 5 years ago Until now	默认的结束点是到现在。
图表	Metrics	下拉列表框，用于筛选图表中的数据，在数据源配置时添加的度量列中选择一个或多个。	Sum(wind_power)	默认是count。
	Series	下拉列表框，用于挑选图表中展示的分组序列	Dim1
	Breakdowns	用于定义序列的分组	Dim2	注意，Breaddown中的列和Series中的列不能重复
	Row limit	显示行数
SQL	Custom Where clause	文本框，用于定制过滤数据的条件	A>5	(关系表图表选项）
	Custom Having Clause	文本框，用于定制过滤聚合结果的条件		(关系表图表选项）
Filters	Filter	三个列表框，分别输入列名，操作符，和值。用于定制序列上的过滤数据的条件		在关系表图表中和Where clause中输入的条件并列取与。

配置完图表选项后，点击定制区左上角的“Query”按钮，即可生成图表，显示在页面右半部分。

4.4.1. 保存图表

点击定制区左上角的“Save as”按钮，即可保存图表。在下方对话框中选择保存的方法。可选覆盖当前图表，或者生成新图表。也可以选择在保存图表的同时把他加到仪表盘中，也可以选择单独保存图表。

4.4.2. 图表展示

在展示区的左上角显示图表名称。点击名称右侧的五角星图标，将收藏这个图表。个人中心中列出所有个人收藏的图表和仪表盘。点击最右侧的编辑图标，将弹出对话框对修改图表属性。

4.4.3. 图表导出

在展示区的右上角绿色或者红色时间标记，显示的是查询耗时。绿色表示查询成功。红色表示查询失败，并在图表区显示失败消息。

点击右侧链接图标可以拷贝图标页面地址，用于复制到其他地方。点击html图标可以拷贝Iframe标签，用于复制到其他地方。

点击Json图标，跳转到新的页面，显示Json格式的图表数据信息。如下图所示。

点击CSV图标，下载图表查询结果数据为CSV格式文件到本地下载路径。

点击query图标，显示Query语句。如果是基于数据库表的图表，显示SQL查询语句，如果是基于时序数据源的图表，显示Json查询语句。

4.4.4. 修改图表属性

在图表列表中图点击图表编辑图表，可对图表属性进行修改。尽量不要修改可视化类型和参数，修改不慎会造成图表失效。

4.4.5. 图表类型

寄云时序数据库系统支持下面几种图表类型：

名称	描述	示例
Pie Chart	饼图
Time Series - Line Chart	时序线图
Time Series - Duax axis Line Chart	时序双轴线图
Time Series - Bar Chart	时序柱状图
Time Series - Percent Change	折线-百分比变化图
Time Series - Stacked	堆积图
Histogram	直方图
Sunburst	旭日图
Sankey	桑基图
Directed Force Layout	关系图
World Map	地图
Markup	标注
Pivot Table	透视表
Table View	表格
Separator	分割
Word Cloud	字云图
Treemap	树图
Calendar Heatmap	日历热力图
Box Plot	箱线图
Bubble Chart	气泡图
Bullet Chart	子弹图
Big Number with Trendline	大数加趋势线
Big Number	大数
Heat map	热力图