全部产品

TSQL查询API

更新时间:2020-06-03 11:28:16

请求路径和方法

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查询语句表示:

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

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

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

  1. 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文件

  1. //sql.json
  2. {"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提交查询

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

查询结果

  1. {
  2. "columns": [
  3. "hostname",
  4. "minV",
  5. "maxV"
  6. ],
  7. "metadata": [
  8. "VARCHAR",
  9. "FLOAT8",
  10. "FLOAT8"
  11. ],
  12. "rows": [
  13. {
  14. "hostname": "host_9",
  15. "minV": "90.49879988870993",
  16. "maxV": "93.8549962369351"
  17. },
  18. {
  19. "hostname": "host_8",
  20. "minV": "0.9174383579092883",
  21. "maxV": "5.997678861502513"
  22. },
  23. {
  24. "hostname": "host_0",
  25. "minV": "0.12036918007593445",
  26. "maxV": "2.6224297271376256"
  27. },
  28. ....
  29. ]
  30. }

SQL 写入

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

写入语法

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

格式要求:

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

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

写入示例

SQL 样例

  1. 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 文件上

  1. //sql_insert.json
  2. {"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') "}
  1. //sql_query.json
  2. {"sql": "select * from tsdb.`sys.cpu.load` limit 1"}
以curl命令行参数形式通过SQL 写入和查询数据
  • 提交写入
    1. curl tsdb_host:tsdb_port/api/sqlquery -d @sql_insert.json
  • 提交查询
    1. curl tsdb_host:tsdb_port/api/sqlquery -d @sql_query.json
    查询结果
  1. {
  2. "columns": [
  3. "dc",
  4. "hostname",
  5. "timestamp",
  6. "load1min",
  7. "load15min",
  8. "load5min"
  9. ],
  10. "metadata": [
  11. "VARCHAR",
  12. "VARCHAR",
  13. "TIMESTAMP",
  14. "VARCHAR",
  15. "VARCHAR",
  16. "VARCHAR"
  17. ],
  18. "rows": [
  19. {
  20. "dc": "datacenter1",
  21. "hostname": "host1",
  22. "timestamp": "2020-06-01 17:56:57.368",
  23. "load1min": "1.0",
  24. "load15min": "0.0",
  25. "load5min": "0.0"
  26. }
  27. ]
  28. }

其他限制

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