TDengine 时序函数 DERIVATIVE 用户手册
DERIVATIVE 函数用户手册（智能电表场景）
1. 函数概述
DERIVATIVE 是 TDengine 的时间序列分析函数，用于计算指定数值列在时间序列上的变化速率（即导数、斜率、增速）。它常用于分析电压、电流、功率等指标随时间的变化趋势，帮助发现突变、异常或趋势变化。
注意：
- DERIVATIVE 只能用于数值类型字段（如
voltage、current、power）。 - 超级表查询时，必须使用
PARTITION BY tbname，确保每个子表的时间线独立有序。 - 不能用于字符串、时间戳等非数值类型。
- 用于复合主键时，若时间戳相同的数据存在多条，则只有对应复合主键最小的数据参与运算。
2. 语法
-- 子表查询
SELECT ts, voltage, DERIVATIVE(voltage, interval, mode) FROM sub_table [WHERE condition] ORDER BY ts;-- 超级表查询（必须分区）
SELECT tbname, ts, voltage, DERIVATIVE(voltage, interval, mode)
FROM super_table
[WHERE condition]
PARTITION BY tbname
ORDER BY tbname, ts;
参数说明
- 第1个参数：数值列名（如 voltage、current、power）
- 第2个参数：间隔（整数，单位为采样点数，最小为1，表示间隔 1s , 可以带时间单位，如 2h 表示 2 小时 ）
- 第3个参数：模式（0 或 1，0 表示普通差分，1 表示归一化到每秒的速率）
示例：
DERIVATIVE(voltage, 1, 0)：计算相邻两点的差值（普通差分）DERIVATIVE(voltage, 1, 1)：计算相邻两点的每秒变化速率
3. 计算过程与返回值说明
3.1 计算过程
假设有如下数据（以电压为例）：
| ts | voltage |
|---|---|
| 2024-09-22 10:00:00 | 220.0 |
| 2024-09-22 10:01:00 | 221.0 |
| 2024-09-22 10:02:00 | 223.0 |
| 2024-09-22 10:03:00 | 222.5 |
普通差分（mode=0）
- DERIVATIVE(voltage, 1, 0) = 当前值 - 上一个值
- 第一行无前值，结果为 NULL
- 第二行：221.0 - 220.0 = 1.0
- 第三行：223.0 - 221.0 = 2.0
- 第四行：222.5 - 223.0 = -0.5
归一化速率（mode=1）
- DERIVATIVE(voltage, 1, 1) = (当前值 - 上一个值) / (当前时间 - 上一个时间，单位秒)
- 假设采样间隔为60秒：
- 第二行：(221.0 - 220.0) / 60 = 0.0167
- 第三行：(223.0 - 221.0) / 60 = 0.0333
- 第四行：(222.5 - 223.0) / 60 = -0.0083
3.2 返回值样式
- 返回行数与输入数据行数一致
- 第一行（或每个分区的第一行）返回 NULL
- 其余行为计算结果，类型为 DOUBLE
示例结果：
| ts | voltage | DERIVATIVE(voltage, 1, 0) | DERIVATIVE(voltage, 1, 1) |
|---|---|---|---|
| 2024-09-22 10:00:00 | 220.0 | NULL | NULL |
| 2024-09-22 10:01:00 | 221.0 | 1.0 | 0.0167 |
| 2024-09-22 10:02:00 | 223.0 | 2.0 | 0.0333 |
| 2024-09-22 10:03:00 | 222.5 | -0.5 | -0.0083 |
4. 函数意义与应用场景
4.1 函数意义
- 趋势分析：快速判断电压、电流、功率等指标的变化速度和方向
- 异常检测：发现突变、跳变、异常波动（如电压骤升/骤降）
- 设备健康监控：识别设备运行状态的异常变化
- 能效分析：分析功率变化速率，辅助能耗优化
4.2 典型应用场景
1. 电压变化速率分析
-- 查询单个设备电压变化速率，间隔 3 分钟
SELECT ts, voltage, DERIVATIVE(voltage, 3m, 1) AS voltage_rate
FROM d001
ORDER BY ts;
2. 多设备电流突变检测
-- 超级表多设备，必须分区，间隔 2 小时
SELECT tbname, ts, current, DERIVATIVE(current, 2h, 0) AS current_diff
FROM meters
WHERE current IS NOT NULL
PARTITION BY tbname
ORDER BY tbname, ts;
3. 功率突变告警
-- 检查功率变化绝对值大于100的时刻
SELECT tbname, ts, power, DERIVATIVE(power, 1, 0) AS power_diff
FROM meters
WHERE ts >= NOW() - 1d
PARTITION BY tbname
ORDER BY tbname, ts;
-- 应用层可筛选 power_diff > 100 或 power_diff < -100
4. 电压变化速率趋势图
-- 取最近24小时电压变化速率
SELECT ts, voltage, DERIVATIVE(voltage, 1, 1) AS voltage_rate
FROM d001
WHERE ts >= NOW() - 24h
ORDER BY ts;
5. 使用注意事项
- 超级表必须分区：用
PARTITION BY tbname，否则结果混乱 - 第一行结果为 NULL：每个分区的首行无前值，返回 NULL
- 仅支持数值类型：不能用于字符串、时间戳等
- 间隔参数：通常为1，表示相邻两点；可设为更大整数，表示跨多点差分
6. 常见错误示例
-- 错误：未分区
SELECT ts, voltage, DERIVATIVE(voltage, 1, 0) FROM meters ORDER BY ts;-- 正确：分区
SELECT tbname, ts, voltage, DERIVATIVE(voltage, 1, 0) FROM meters PARTITION BY tbname ORDER BY tbname, ts;-- 错误：用于字符串
SELECT DERIVATIVE(location, 1, 0) FROM meters; -- 错误
7. 总结
DERIVATIVE 函数是智能电表时序数据分析中用于计算变化速率的关键工具。它能帮助用户快速发现趋势、突变和异常，适用于电压、电流、功率等数值型指标的变化分析。使用时要注意分区、排序和参数类型，确保结果准确。
关于 TDengine
TDengine 专为物联网IoT平台、工业大数据平台设计。其中，TDengine TSDB 是一款高性能、分布式的时序数据库（Time Series Database），同时它还带有内建的缓存、流式计算、数据订阅等系统功能；TDengine IDMP 是一款AI原生工业数据管理平台，它通过树状层次结构建立数据目录，对数据进行标准化、情景化，并通过 AI 提供实时分析、可视化、事件管理与报警等功能。