TSQL查询API - 时序数据库 TSDB

本文介绍TSQL查询API的方法。

请求路径和方法

TSQL当前仅支持通过HTTP协议方式访问，通过/api/sqlquery接口进行数据请求。接口请求参数和协议介绍如下：

请求路径	请求方法	描述
/api/sqlquery	GET/POST	以SQL语句查询时序数据。

请求内容

请求内容 JSON 格式

名字	类型	是否必需	描述	默认值	举例
sql	string	是	一个SQL查询语句。	无	select min( `value`) as minV, max(`value`) as maxV`from tsdb.`cpu.usage_system`<br />where `timestamp`` between ‘2019-01-01’ and ‘2019-01-02’

SQL查询结果

查询结果JSON格式

名字	类型	描述	举例
columns	string类型的数组	查询结果每个column的列名。	[“hostname”, “minV”, “maxV”]
metadata	string类型的数组	查询结果每个column的列类型。	[“VARCHAR”, “FLOAT8”, “FLOAT8”]
rows	map类型的数组	查询结果行，每行是一个map，列名是key，列的值是value。	[{ “hostname”: “host_9”, “minV”: “90.49879988870993”, “maxV”: “93.8549962369351”},{ “hostname”: “host_8”, “minV”: “0.9174383579092883”, “maxV”: “5.997678861502513”},…]

查询示例

获得cpu.usage_system这个度量在“2019-03-01 00:00:00” 到“2019-03-01 00:01:00”这1分钟之内的在每台机器上的最小值和最大值，可以用下面的SQL查询语句表示：

select hostname, min(`value`) as minV, max(`value`) as maxV 
from tsdb.`cpu.usage_system` 
where `timestamp` between '2019-03-01 00:00:00' and '2019-03-01 00:01:00'
group by hostname

两种方式把这个SQL语句提交到TSDB。

以curl命令行参数形式指定SQL查询语句

curl -H "Content-Type: application/json" -d $'{"sql":"select hostname, min(`value`) as minV, max(`value`) as maxV from tsdb.`cpu.usage_system` where `timestamp` between \'2019-03-01 00:00:00\' and \'2019-03-01 00:01:00\' group by hostname"}' http://tsdb_host:tsdb_port/api/sqlquery

注意

在上面的命令行中，JSON的字符串被单引号包含，所以JSON字符串内部出现的单引号，需要使用转义符\。

如果把JSON字符串放进一个文件，则不需要使用转义符。

SQL查询语句放在JSON文件

//sql.json
{"sql": "select hostname, min(`value`) as minV, max(`value`) as maxV from tsdb.`cpu.usage_system` where `timestamp` between '2019-03-01 00:00:00' and '2019-03-01 00:01:00' group by hostname"}

用curl提交查询

curl -H "Content-Type: application/json" -d @sql.json http://tsdb_host:tsdb_port/api/sqlquery

查询结果

{
  "columns": [
    "hostname",
    "minV",
    "maxV"
  ],
  "metadata": [
    "VARCHAR",
    "FLOAT8",
    "FLOAT8"
  ],
  "rows": [
    {
      "hostname": "host_9",
      "minV": "90.49879988870993",
      "maxV": "93.8549962369351"
    },
    {
      "hostname": "host_8",
      "minV": "0.9174383579092883",
      "maxV": "5.997678861502513"
    },
    {
      "hostname": "host_0",
      "minV": "0.12036918007593445",
      "maxV": "2.6224297271376256"
    },
   ....
  ]
}

SQL写入

TSDB高可用版本对TSQL进行了升级。除了SELECT查询SQL，还支持通过insert SQL写入数据到TSDB。详细内容如下：

写入语法

INSERT [INTO] tbl_name
    [(`col_name` [, `col_name`] ... `timestamp`)]
    { {VALUES | VALUE} (value_list) [, (value_list)] ...
    }

格式要求：

insert语法和标准SQL大体相同，但是根据时序数据库的特点有某些特殊要求。主要体现在col_name列名的命名上：

根据时序特点，timestamp为保留字段，输入中必须存在名为“timestamp”的列，且该列类型为“timestamp”。
除了timestamp列以外，其它列须自带时序前缀标识（tag vs field），并通过分隔符“：”与列名链接。前缀并不是列名的一部分。
insert只支持简单语法，暂不支持函数表达式，insert from select 等复杂SQL。
insert 写入采用多值模型写入数据，tsql 写入的数据通过restful API查询时，需要使用多值协议/api/mquery。

写入示例

SQL 样例

insert into tsdb.`sys.cpu.load` ('tag:hostname', 'tag:dc', 'timestamp', 'field:load1min', 'field:load5min', 'field:load15min') values ('host1', 'datacenter1', '2020-06-01 18:56:57.368', '1.0', '0.0', '0.0'), ('host1', 'datacenter1', '2020-06-01 18:57:57.368', '2.0', '0.0', '0.0')

SQL 语句放在JSON文件上

//sql_insert.json
{"sql": "insert into tsdb.`sys.cpu.load` ('tag:hostname', 'tag:dc', 'timestamp', 'field:load1min', 'field:load5min', 'field:load15min') values ('host1', 'datacenter1', '2020-06-01 18:56:57.368', '1.0', '0.0', '0.0'), ('host1', 'datacenter1', '2020-06-01 18:57:57.368', '2.0', '0.0', '0.0') "}

//sql_query.json
{"sql": "select * from tsdb.`sys.cpu.load` limit 1"}

以curl命令行参数形式通过SQL 写入和查询数据

提交写入

curl tsdb_host:tsdb_port/api/sqlquery -d @sql_insert.json

提交查询

curl tsdb_host:tsdb_port/api/sqlquery -d @sql_query.json

查询结果

{
  "columns": [
    "dc",
    "hostname",
    "timestamp",
    "load1min",
    "load15min",
    "load5min"
  ],
  "metadata": [
    "VARCHAR",
    "VARCHAR",
    "TIMESTAMP",
    "VARCHAR",
    "VARCHAR",
    "VARCHAR"
  ],
  "rows": [
    {
      "dc": "datacenter1",
      "hostname": "host1",
      "timestamp": "2020-06-01 17:56:57.368",
      "load1min": "1.0",
      "load15min": "0.0",
      "load5min": "0.0"
    }
  ]
}

其他限制

目前TSQL只支持写入和查询2个SQL接口。数据删除，建表操作暂不支持。
高可用版TSQL写入敬请期待。