TSQL查询API
本文介绍TSQL查询API的方法。
请求路径和方法
TSQL当前仅支持通过HTTP协议方式访问,通过/api/sqlquery接口进行数据请求。接口请求参数和协议介绍如下:
请求路径 | 请求方法 | 描述 |
---|---|---|
/api/sqlquery | GET/POST | 以SQL语句查询时序数据。 |
请求内容
请求内容 JSON 格式
名字 | 类型 | 是否必需 | 描述 | 默认值 | 举例 |
---|---|---|---|---|---|
sql | string | 是 | 一个SQL查询语句。 | 无 | select min( |
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写入敬请期待。
- 本页导读 (1)