TSQL查询API

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

请求路径和方法

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

请求路径

请求方法

描述

/api/sqlquery

GET/POST

以SQL语句查询时序数据。

请求内容

请求内容 JSON 格式

名字

类型

是否必需

描述

默认值

举例

sql

string

一个SQL查询语句。

select min( value) as minV, max(value) as maxVfrom 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写入敬请期待。