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 提供实时分析、可视化、事件管理与报警等功能。