TSQL查询API

请求路径和方法

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

请求内容

请求内容 JSON 格式

SQL查询结果

查询结果JSON格式

查询示例

假设我们要执行下面的查询，获得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 写入敬请期待。