TDengine 函数完整参考 — 聚合、时序、字符串、时间、数学

分类：10.SQL 参考 | 篇章：03 函数完整参考

适用版本：TDengine v3.x（v3.3.x / v3.4.x） | 最后更新：2026-07-16

TDengine 提供 100+ 内置函数，覆盖聚合、时序专用、字符串处理、时间运算、数学计算、类型转换。本文按类别速查并给出典型用法。

函数速查表

类别	代表函数
聚合	COUNT, SUM, AVG, MIN, MAX, FIRST, LAST, MODE
统计	STDDEV, VAR_POP, PERCENTILE, APERCENTILE, HISTOGRAM
时序	DIFF, DERIVATIVE, MAVG, TWA, INTERP, IRATE, STATECOUNT
选择	TOP, BOTTOM, SAMPLE, TAIL, UNIQUE
窗口元数据	_WSTART, _WEND, _WDURATION, _QSTART, _QEND
字符串	CONCAT, SUBSTR, LENGTH, UPPER, LOWER, TRIM
时间	NOW, TODAY, TIMEDIFF, TIMETRUNCATE, TO_CHAR, TO_TIMESTAMP
数学	ABS, ROUND, FLOOR, CEIL, POW, LOG, SIN, COS
类型	CAST, TO_JSON
位运算	& \| ^ ~ << >>

详细解析

1. 聚合函数

sql 复制代码

-- 计数
COUNT(*)              -- 行数
COUNT(col)            -- 非空行数
COUNT(DISTINCT col)   -- 去重计数

-- 求和与均值
SUM(col)
AVG(col)

-- 极值
MIN(col)
MAX(col)

-- 时序首尾
FIRST(col)            -- 时间最早
LAST(col)             -- 时间最晚
LAST_ROW(col)         -- 最新整行

2. 统计函数

sql 复制代码

-- 标准差/方差
STDDEV(col)
VAR_POP(col)

-- 百分位
PERCENTILE(col, 50)            -- 精确（慢）
APERCENTILE(col, 50)           -- 近似（快，推荐）
APERCENTILE(col, 99, 't-digest') -- 指定算法

-- 直方图
HISTOGRAM(col, 'linear_bin', '{"start":0,"width":10,"count":10}', 0)

-- 协方差
HYPERLOGLOG(col)               -- 近似去重计数（HLL）

3. 时序专用函数

sql 复制代码

-- DIFF: 相邻值差
SELECT ts, current, DIFF(current) FROM d001;
-- ts=T2 时 DIFF = current(T2) - current(T1)

-- DERIVATIVE: 导数
SELECT ts, DERIVATIVE(current, 1s, 0) FROM d001;
-- (current_change) / time_change，每秒变化率

-- MAVG: 移动平均
SELECT ts, MAVG(current, 5) FROM d001;
-- 5 个数据点的滑动平均

-- TWA: 时间加权平均
SELECT TWA(current) FROM d001 WHERE ts > now-1h;
-- 适合采样间隔不均的数据

-- INTERP: 插值
SELECT INTERP(current) FROM d001 
WHERE ts BETWEEN '2026-06-04 12:00' AND '2026-06-04 13:00' 
EVERY(1m) FILL(LINEAR);
-- 按指定时间生成插值结果

-- IRATE: 瞬时变化率（基于最后两个数据点）
SELECT IRATE(counter) FROM d001;

-- STATECOUNT: 满足状态的连续点数
SELECT STATECOUNT(current, 'gt', 100) FROM d001;

-- STATEDURATION: 满足状态的持续时长
SELECT STATEDURATION(current, 'gt', 100, 1s) FROM d001;

4. 选择函数

sql 复制代码

-- TOP/BOTTOM
SELECT TOP(current, 10) FROM meters;
SELECT BOTTOM(current, 5) FROM meters;

-- 采样
SELECT SAMPLE(current, 100) FROM meters;

-- 尾部
SELECT TAIL(current, 10) FROM meters;

-- 唯一值
SELECT UNIQUE(location) FROM meters;

5. 时间函数

sql 复制代码

-- 当前时间
NOW                            -- 当前时间戳
NOW() + 1h
TODAY()                        -- 今天 00:00

-- 时间格式化
TO_CHAR(ts, 'yyyy-mm-dd HH:MI:SS')

-- 字符串转时间
TO_TIMESTAMP('2026-06-04 12:00:00', 'yyyy-mm-dd HH:MI:SS')

-- 时间差
TIMEDIFF(ts1, ts2, 1m)         -- 单位：1s/1m/1h/1d

-- 时间截断
TIMETRUNCATE(ts, 1h)           -- 截断到小时

-- 时区
TIMEZONE()

-- 当前时间戳
CURRENT_TIMESTAMP

-- 时间加减
ts + 1h, ts - 30m

6. 字符串函数

sql 复制代码

CONCAT('Hello', ' ', 'World')
CONCAT_WS('-', 'a', 'b', 'c')

SUBSTR(str, 1, 5)
LENGTH(str)                    -- 字符串字节长
CHAR_LENGTH(str)               -- 字符数

UPPER(str)
LOWER(str)
TRIM(str)
LTRIM(str), RTRIM(str)

REPLACE(str, 'old', 'new')

LOCATE('sub', str)             -- 子串位置

7. 数学函数

sql 复制代码

ABS(x)
ROUND(x, n)                    -- 四舍五入
FLOOR(x), CEIL(x)
POW(x, y), POWER(x, y)
LOG(x), LOG10(x)
SQRT(x)

SIN(x), COS(x), TAN(x)
ASIN(x), ACOS(x), ATAN(x)

PI()
RAND()
MOD(x, y)

8. 类型转换与条件

sql 复制代码

-- 类型转换
CAST(col AS INT)
CAST(col AS VARCHAR(20))
CAST(ts AS BIGINT)             -- 时间戳转毫秒

-- 条件函数
CASE WHEN cond THEN v1 ELSE v2 END
COALESCE(c1, c2, c3)           -- 第一个非 NULL
NULLIF(c1, c2)                 -- 相等返回 NULL

-- JSON
TO_JSON('{"a":1}')             -- 文本转 JSON
col->'$.field'                 -- JSON 字段提取（视版本）

9. 窗口元数据函数

sql 复制代码

SELECT 
  _wstart,          -- 窗口开始
  _wend,            -- 窗口结束
  _wduration,       -- 窗口时长（毫秒）
  _qstart,          -- 查询开始
  _qend,            -- 查询结束
  AVG(current) 
FROM meters 
WHERE ts > now-1d 
INTERVAL(1h);

代码示例

综合时序分析

sql 复制代码

-- 设备性能分析
SELECT 
  tbname,
  _wstart,
  AVG(current) AS avg_c,
  STDDEV(current) AS std_c,
  APERCENTILE(current, 95) AS p95,
  MAX(current) - MIN(current) AS range_c,
  STATECOUNT(current, 'gt', 100) AS over_count,
  DERIVATIVE(SUM(current), 1h, 0) AS hourly_growth
FROM meters 
WHERE ts > now-1d 
PARTITION BY tbname 
INTERVAL(1h);

数据补全与插值

sql 复制代码

-- 5 分钟均匀插值
SELECT INTERP(current) AS current 
FROM d001 
WHERE ts BETWEEN '2026-06-04' AND '2026-06-05' 
EVERY(5m) 
FILL(LINEAR);

字符串与时间处理

sql 复制代码

-- 按天分组统计
SELECT 
  TO_CHAR(ts, 'yyyy-mm-dd') AS day,
  AVG(current) 
FROM meters 
WHERE ts > now-30d 
GROUP BY day;

-- 转大写匹配
SELECT * FROM meters WHERE UPPER(location) = 'BEIJING';

性能考量

函数性能等级

函数	性能	备注
COUNT/SUM/AVG/MIN/MAX	极快	用块 SMA
FIRST/LAST	极快	用 LAST 缓存
APERCENTILE	快	近似算法
PERCENTILE	慢	精确，扫全部
DIFF/DERIVATIVE	中	行间计算
MAVG	中	窗口聚合
TWA	中	复杂时间加权
INTERP	中	插值计算

选择建议

需求	推荐
计数	COUNT
去重计数	COUNT(DISTINCT)（小数据）/ HYPERLOGLOG（大数据）
百分位	APERCENTILE（一般）/ PERCENTILE（必须精确）
移动均值	MAVG
不均匀采样均值	TWA
等距插值	INTERP

FAQ

Q1: 自定义函数 (UDF) 怎么用？

支持 C/C++ UDF。需编译为 so，CREATE FUNCTION 注册：

sql 复制代码

CREATE AGGREGATE FUNCTION fn_name AS '/path/to/lib.so' OUTPUTTYPE DOUBLE;

Q2: COUNT(*) 和 COUNT(col) 区别？

COUNT(*): 所有行
COUNT(col): col 非 NULL 的行
性能：COUNT(*) 用块 SMA 最快

Q3: PERCENTILE 卡死？

精确计算需排序所有数据。大数据用 APERCENTILE。

Q4: DIFF 第一行是什么？

NULL（无前一行可比）。

Q5: 函数嵌套支持吗？

支持但有限。聚合函数不能嵌套聚合函数（除非通过子查询）。

参考

系统构架篇

数据模型

存储引擎

查询引擎

数据写入

数据订阅

预聚合

索引

SQL 语句

01-《TDengine DDL》
02-《TDengine DML SELECT》

关于 TDengine

TDengine 专为物联网IoT平台、工业大数据平台设计。其中，TDengine TSDB 是一款高性能、分布式的时序数据库（Time Series Database），同时它还带有内建的缓存、流式计算、数据订阅等系统功能；TDengine IDMP 是一款AI原生工业数据管理平台，它通过树状层次结构建立数据目录，对数据进行标准化、情景化，并通过 AI 提供实时分析、可视化、事件管理与报警等功能。