支持SQL查询
更新时间：2025-08-22
介绍
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。