介绍

TSDB支持SQL的查询接口，可以通过SQL语言实现对TSDB数据的筛选和查询。利用SQL的强大能力，用户即可以熟悉方便地对数据进行操作，也可以充分利用SQL函数的计算能力，挖掘数据价值。

基础操作说明

• SQL语句的table对应TSDB的metric
• SQL语句中的field对应TSDB的timestamp、field、tag
• SQL的查询条件中如果包含中文字符，应当使用单引号括起来，如果只包含英文字符，则单引号和双引号均可

举个例子：一个智能电表监控的物联网集成方案，采集了智能电表的各个监控点的数据。在TSDB中这样组织（如下图），metric为SmartMeter，表示TSDB存的是智能电表的数据，每个电表有power和MeterCurrent两个域（field），用两个tag，即MeterID和City，来代表每个数据点来自哪个电表ID和城市。电表每5s上传一次功率值和电流值。

可以将上表看成一个二维表，针对二维表来写SQL语句

应用场景一：要过滤功率值大于400、电流值小于5，电表ID为2345HDYE的数据

select timestamp, power, MeterCurrent, MeterID, City from SmartMeter where power > 400 and current<5 and MeterID = '2345HDYE'

应用场景二：电表ID为2345HDYE的电表中，返回每10秒的功率平均值

select time_bucket(timestamp, '10 seconds') as TIME, avg(power) as AVG_POWER from SmartMeter group by time_bucket(timestamp, '10 seconds') order by time_bucket(timestamp, '10 seconds')

应用场景三：join两个metric

两个metric如下表

用MeterID将两个表进行join，SQL语句如下： select * from SmartMeter join SmartTemperature on SmartMeter.MeterID = SmartTemperature.MeterID ;

得到以下数据：

TSDB_SQL_01-1

SQL函数

• 查询函数举例
  

类型	SQL	解释
时间查询	select timestamp from metric	timestamp: 固定查询时间戳关键字，系统默认使用UTC时间 metric：用户需要查询的metric名称
单域查询	select value from metric	value：用户需要查询的field的名称 metric：用户需要查询的metric名称
Tag查询	select tag_key from metric	tag_key：用户需要查询的tag的key metric：用户需要查询的metric名称
多列查询	select timestamp,field1 from metric select * from metric	tag_key：用户需要查询的tag的key field1：用户需要查询的field的名称 metric：用户需要查询的metric名称
按照时间排序	select timestamp, value from metric order by timestamp select timestamp, value from metric order by timestamp desc select timestamp, value from metric order by timestamp offset 1 limit 1	order by：查询排序方式 asc/desc：升序/降序 offset和limit：排序后从第offset条开始，取limit条
带过滤查询	select timestamp, value from metric where value > 30 and timestamp >150937263000	value > 30：过滤value的值，UTC时间戳精度毫秒
分组查询	select tag_key, count(1) from metric group by tag_key	group by tag_key：按照tag的Key值分组
聚合查询	select time_bucket(timestamp, '2 days') as DAY, sum(value) as SUM from metric group by time_bucket(timestamp, '2 days') order by time_bucket(timestamp, '2 days')	time_bucket: 时间聚合函数 timestamp：实际数据点中的时间戳字段（不用修改） 2 days：时间窗口是2天 group by time_bucket：按照时间2 days分组 sum(value)：聚合2 days的value的值 time_bucket支持日历对齐和自定义起始时间： 如time_bucket(timestamp, 1dc)，字符'c'表示日历对齐。时间单位请参考文档时间单位 窗口的默认起始时间是2000-01-01 00:00:00，如需自定义起始时间可以将'2 days'改成'2 days,2019-01-01 00:00:00'，即表示从2019-01-01开始 每2天一个时间窗口。 日历对齐规则示例如下： 如time_bucket(timestamp,'1 dc,2019-01-01 12:00:00') 则第一个窗口是01月01日12:00:00.000 - 01月01日23:59:59.99 第二个窗口是01月02日00:00:00.000 - 01月02日23:59:59.99 以此类推
自定义函数计算查询	select timestamp, ((field2 - field1) * 10) as RESULT, tag_key from metric	(field2 - field1) * 10 ：用户自定义函数计算

• SQL查询常用的时间函数。

分类	支持函数	举例	说明
日期时间操作符	+/-	mysql> select (date '2012-08-08' + interval '2' day) 2012-08-10 mysql> select (timestamp '2012-08-08 01:00' + interval '29' hour) 2012-08-09 06:00:00.000 mysql> select (date '2012-08-08' - interval '2' day) 2012-08-06 mysql> select (timestamp '2012-10-31 01:00' - interval '1' month) 2012-09-30 01:00:00.000	操作符
时区转换	AT TIME ZONE	mysql> SELECT timestamp '2012-10-31 01:00 UTC' AT TIME ZONE 'America/Los_Angeles' 2012-10-30 18:00:00.000 America/Los_Angeles mysql> SELECT timestamp '2012-10-31 01:00 UTC' AT TIME ZONE 'Asia/Shanghai' 2012-10-31 09:00:00.000 Asia/Shanghai	UTC时区转换
日期和时间函数	current_date current_timestamp from_unixtime(unix_timestamp) now() to_unixtime(timestamp) cast(to_unixtime(timestamp) as bigint)	mysql> select current_date 2021-04-21 mysql> select current_timestamp 2021-04-21 10:59:56.378 UTC mysql> select from_unixtime(1619031748); 2021-04-21 19:02:28.000 mysql> select now() 2021-04-21 11:01:38.221 UTC mysql> select to_unixtime(timestamp '2021-04-21 19:02:28') 1.619031748E9 mysql> select cast(to_unixtime(timestamp '2021-04-21 19:02:28') as bigint) 1619031748	日期时间相关
截取函数	date_trunc(unit,timestamp)	mysql> select date_trunc('day',timestamp '2021-04-21 19:02:28') 2021-04-21 00:00:00.000 mysql> select date_trunc('hour',timestamp '2021-04-21 19:02:28') 2021-04-21 19:00:00.000	截取timestamp的一部分
时间段	date_add(unit,bigint,timestamp)	mysql> select date_add('hour', 8, timestamp '2021-04-21 19:02:28') 2021-04-22 03:02:28.000	基于某个时间加减
持续时长	parse_duration(string)	mysql> SELECT parse_duration('5m') 0 00:05:00.000	字符串格式的时间转化
日期格式化	date_format(timestamp,string format)	mysql> select date_format(timestamp '2021-04-21 19:02', '%Y-%m-%d %H:%i:%s') 2021-04-21 19:02:00	格式转化
提取函数	day_of_week(timestamp)	mysql> select day_of_week(timestamp '2021-04-21 19:02') 3	返回bigint

• 自定义函数

TSDB支持标准ANSI SQL语义，选取常用的部分自定义函数如下所示。

自定义函数说明：

分类	支持函数	举例	说明
条件表达式	CASE	SELECT field1,                CASE field1                          WHEN 1 THEN 'one'                          WHEN 2 THEN 'two'                          ELSE 'many'                END FROM metric	case表达式
条件表达式	IF	SELECT field1,                IF (field1>100,1,0) as result FROM metric	if表达式，if(condition, true_value)或 if(condition, true_value, false_value)
条件表达式	COALESCE	SELECT field1, field2,                COALESCE (field1, field2) as result FROM metric	返回列表中第一个非空值
计算函数	abs(x)	SELECT field1,                 abs (field1) as result FROM metric	返回x的绝对值
计算函数	sqrt(x)	SELECT field1,                 sqrt (field1) as result FROM metric	返回x的平方根
计算函数	cbrt(x)	SELECT field1,                 cbrt (field1) as result FROM metric	返回x的立方根
计算函数	ceil(x)	SELECT field1,                ceil (field1) as result FROM metric	返回不小于x的最小整数值
计算函数	ceiling(x)	同ceil(x)	返回大于或等于x的最小整数值
计算函数	floor(x)	SELECT field1,                floor (field1) as result FROM metric	返回小于或等于x的最大整数值
字符串操作	||	SELECT field1 || field2 as result FROM metric	字符串级联
聚合函数	avg(x)	SELECT time_bucket(timestamp, '2 days') as DAY, avg(field1) as result FROM metric group by time_bucket(timestamp, '2 days') order by time_bucket(timestamp, '2 days')	返回field1的平均值
聚合函数	count(*)	SELECT count(*) as result FROM metric where timestamp < 1525611901	返回数量
聚合函数	count(x)	SELECT time_bucket(timestamp, '2 days') as DAY, count(field1) as count FROM metric group by time_bucket(timestamp, '2 days') order by time_bucket(timestamp, '2 days')	返回非空值的数量
聚合函数	max_by(x, y)	SELECT max_by(field1,field2) as result FROM metric where timestamp < 1525611901000	返回y最大时的x，UTC时间戳精度毫秒
聚合函数	min_by(x, y)	SELECT min_by(field1,field2) as result FROM metric where timestamp < 1525611901000	返回y最小时的x，UTC时间戳精度毫秒
聚合函数	max(x)	SELECT max(field1) as result FROM metric where timestamp < 1525611901000	返回x的最大值，UTC时间戳精度毫秒
聚合函数	min(x)	SELECT min(field1) as result FROM metric where timestamp < 1525611901000	返回x的最小值，UTC时间戳精度毫秒
聚合函数	sum(x)	SELECT time_bucket(timestamp, '2 days') as DAY, sum(field1) as sum FROM metric group by time_bucket(timestamp, '2 days') order by time_bucket(timestamp, '2 days')	返回x的和值
聚合函数	first_value(x)	SELECT field2, first_value(field1) OVER (PARTITION BY field2 ORDER BY timestamp) FROM metric WHERE timestamp >=0 AND timestamp <= 1600 AND field2 IN (1, 2) GROUP BY (field2, field1) （建议field2对应到TSDB的tag）	返回x的首值
聚合函数	last_value(x)	SELECT field2, last_value(field1) OVER (PARTITION BY field2 ORDER BY timestamp RANGE BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING) FROM metric WHERE timestamp >=0 AND timestamp <= 1600 AND field2 IN (1, 2) GROUP BY (field2, field1) （建议field2对应到TSDB的tag）	返回x的末值

TSDB SDK的SQL使用

TSDB Java-SDK、Node-SDK、Python-SDK以及API均支持了SQL查询，具体使用请分别参考Java-SDK、Node-SDK、Python-SDK、API。