TDengine 时序函数 STATEDURATION 用户手册

STATEDURATION 函数用户手册（智能电表场景）

1. 函数概述

STATEDURATION 是 TDengine 的时序状态函数，用于计算满足某个条件的连续记录的持续时间。该函数在智能电表监控系统中特别适用于分析连续异常状态的持续时长，如高电压持续时间、过载持续时间等，为故障分析和设备维护提供重要的时间维度数据。

STATEDURATION 函数概述表格

项目	详细说明
函数名称	STATEDURATION
功能说明	返回满足某个条件的连续记录的持续时间，结果作为新的一列追加在每行后面。条件根据参数计算，如果条件为 true 则累加持续时间，条件为 false 则重置为 -1，如果数据为 NULL，跳过该条数据。
语法格式	STATEDURATION(expr, oper, val, unit)
参数说明	expr : 数值列表达式 oper : 比较操作符 val : 比较数值 unit: 时间单位
操作符范围 (oper)	"LT" (小于) "GT" (大于) "LE" (小于等于) "GE" (大于等于) "NE" (不等于) "EQ" (等于) 注：不区分大小写，需用引号包围
数值范围 (val)	数值型
时间单位 (unit)	1s (秒) 1m (分钟) 1h (小时) 1d (天) 1w (周)
返回结果类型	INTEGER
适用数据类型	数值类型 (TINYINT, SMALLINT, INT, BIGINT, FLOAT, DOUBLE)
计算规则	条件为 true：累加持续时间 条件为 false：重置为 -1 数据为 NULL：跳过该条数据
嵌套子查询支持	支持子查询
适用于	表和超级表
超级表使用要求	必须使用 PARTITION BY tbname（不能按标签分区）
SELECT 语句限制	每个 SELECT 语句只能包含一个 STATEDURATION 函数
WHERE 子句限制	不能直接在 WHERE 子句中使用，需通过嵌套查询实现
使用限制	不能和窗口操作一起使用 例如：INTERVAL / STATE_WINDOW / SESSION_WINDOW
应用场景	异常状态持续时间分析 设备故障时长统计 质量监控时间分析 性能指标持续时间评估

使用示例对照表

场景	正确用法 ✅	错误用法 ❌
基本使用	SELECT STATEDURATION(voltage, "GE", 240, 1s) FROM d1;	SELECT STATEDURATION(voltage, GE, 240, 1s) FROM d1;
多函数限制	SELECT ts, voltage, STATEDURATION(voltage, "GE", 240, 1m) FROM d1;	SELECT STATEDURATION(voltage, "GE", 240, 1s), STATEDURATION(current, "GT", 20, 1s) FROM d1;
WHERE 过滤	SELECT * FROM (SELECT ts, STATEDURATION(voltage, "GE", 240, 1m) AS dur FROM d1) WHERE dur >= 5;	SELECT ts FROM d1 WHERE STATEDURATION(voltage, "GE", 240, 1m) >= 5;
超级表使用	SELECT STATEDURATION(voltage, "GE", 240, 1h) FROM meters PARTITION BY tbname;	SELECT STATEDURATION(voltage, "GE", 240, 1h) FROM meters PARTITION BY device_id;
子查询支持	SELECT STATEDURATION(voltage, "GE", 240, 1m) FROM (SELECT * FROM d1 WHERE ts >= NOW()-1h);	-

2. 语法

STATEDURATION(expr, oper, val, unit)

参数说明

• expr：需要进行状态检测的数值列
• oper：比较操作符，支持 "LT", "GT", "LE", "GE", "NE", "EQ"
• val：比较的数值
• unit：时间单位，支持 1s, 1m, 1h, 1d, 1w

返回值说明

• 返回类型：INTEGER
• 计算规则 ：
  • 条件为 true：累加持续时间（以指定单位计算）
  • 条件为 false：重置为 -1
  • 数据为 NULL：跳过该条数据

3. 计算过程与返回值说明

3.1 基本计算示例

假设有如下智能电表电压数据（每分钟采集一次）：

时间戳	电压值 (V)
10:00:00	220.0
10:01:00	245.0
10:02:00	248.0
10:03:00	252.0
10:04:00	235.0
10:05:00	250.0
10:06:00	252.0

计算 STATEDURATION(voltage, "GE", 240, 1m)

SELECT ts, voltage, STATEDURATION(voltage, "GE", 240, 1m) AS high_voltage_duration 
FROM d1 
ORDER BY ts;

结果示例：

ts	voltage	high_voltage_duration
10:00:00	220.0	-1
10:01:00	245.0	1
10:02:00	248.0	2
10:03:00	252.0	3
10:04:00	235.0	-1
10:05:00	250.0	1
10:06:00	252.0	2

3.2 不同时间单位示例

-- 以秒为单位（适用于高频采集）
SELECT ts, voltage, STATEDURATION(voltage, "GE", 240, 1s) AS duration_sec FROM d1;

-- 以小时为单位（适用于长期分析）
SELECT ts, voltage, STATEDURATION(voltage, "GE", 240, 1h) AS duration_hour FROM d1;

3.3 NULL 值处理

STATEDURATION 会跳过 NULL 值，不影响持续时间计算：

ts	voltage	high_voltage_duration
10:00:00	245.0	1
10:02:00	248.0	2
10:03:00	235.0	-1

4. 智能电表应用场景

4.1 数据库结构

-- 超级表
CREATE STABLE meters (
    ts TIMESTAMP,
    voltage FLOAT,
    current FLOAT,
    power FLOAT
) TAGS (
    device_id VARCHAR(50),
    location VARCHAR(50)
);

-- 子表
CREATE TABLE d1 USING meters TAGS ('meter001', 'California.SanFrancisco');

4.2 电压异常持续时间监控

-- 监控高电压持续时间
SELECT 
    ts,
    voltage,
    STATEDURATION(voltage, "GE", 240, 1m) AS high_voltage_duration_min
FROM d1
WHERE ts >= NOW() - 2h
ORDER BY ts;

-- 监控低电压持续时间
SELECT 
    ts,
    voltage,
    STATEDURATION(voltage, "LE", 200, 1m) AS low_voltage_duration_min
FROM d1
WHERE ts >= NOW() - 1h
ORDER BY ts;

4.3 电流过载持续时间检测

-- 检测过载持续时间
SELECT 
    ts,
    current,
    STATEDURATION(current, "GT", 20, 1m) AS overload_duration_min
FROM d1
WHERE ts >= NOW() - 2h
ORDER BY ts;

-- 检测断电持续时间
SELECT 
    ts,
    current,
    STATEDURATION(current, "EQ", 0, 1s) AS outage_duration_sec
FROM d1
ORDER BY ts;

4.4 超级表监控（使用 PARTITION BY tbname）

-- 按子表分区监控所有设备的电压异常持续时间
SELECT 
    ts,
    tbname,
    voltage,
    STATEDURATION(voltage, "GE", 240, 1m) AS high_voltage_duration_min
FROM meters
WHERE ts >= NOW() - 30m
PARTITION BY tbname
ORDER BY tbname, ts;

5. 嵌套查询与过滤应用

5.1 过滤长时间异常状态

-- 查找持续30分钟以上的高电压记录
SELECT ts, voltage, high_voltage_duration_min
FROM (
    SELECT ts, voltage, STATEDURATION(voltage, "GE", 240, 1m) AS high_voltage_duration_min
    FROM d1
    WHERE ts >= NOW() - 4h
    ORDER BY ts
) 
WHERE high_voltage_duration_min >= 30;

5.2 状态分级报警

-- 基于持续时间的分级报警
SELECT 
    ts,
    voltage,
    high_voltage_duration_min,
    CASE 
        WHEN high_voltage_duration_min >= 60 THEN '严重报警'
        WHEN high_voltage_duration_min >= 30 THEN '一般报警'
        WHEN high_voltage_duration_min >= 10 THEN '预警'
        WHEN high_voltage_duration_min = -1 THEN '正常'
        ELSE '轻微异常'
    END AS alarm_level
FROM (
    SELECT 
        ts,
        voltage,
        STATEDURATION(voltage, "GE", 240, 1m) AS high_voltage_duration_min
    FROM d1
    WHERE ts >= NOW() - 2h
    ORDER BY ts
)
WHERE high_voltage_duration_min >= 10;

6. 使用限制

6.1 单个 STATEDURATION 函数限制

-- ❌ 错误：不能在同一个 SELECT 中使用多个 STATEDURATION
SELECT 
    ts,
    voltage,
    current,
    STATEDURATION(voltage, "GE", 240, 1m) AS high_voltage_duration,
    STATEDURATION(current, "GT", 20, 1m) AS overload_duration
FROM d1;

-- ✅ 正确：每次只使用一个 STATEDURATION
SELECT 
    ts,
    voltage,
    STATEDURATION(voltage, "GE", 240, 1m) AS high_voltage_duration
FROM d1;

6.2 超级表使用限制

-- ❌ 错误：不能按标签分区（会导致时间序列混乱）
SELECT STATEDURATION(voltage, "GE", 240, 1m) FROM meters PARTITION BY device_id;
SELECT STATEDURATION(voltage, "GE", 240, 1m) FROM meters PARTITION BY location;

-- ❌ 错误：不能使用 GROUP BY
SELECT tbname, STATEDURATION(voltage, "GE", 240, 1m) FROM meters GROUP BY tbname;

-- ✅ 正确：只能使用 PARTITION BY tbname
SELECT tbname, STATEDURATION(voltage, "GE", 240, 1m) FROM meters PARTITION BY tbname;

6.3 WHERE 子句限制

-- ❌ 错误：不能在 WHERE 子句中直接使用
SELECT ts, voltage 
FROM d1 
WHERE STATEDURATION(voltage, "GE", 240, 1m) >= 30;

-- ✅ 正确：使用嵌套查询
SELECT ts, voltage, dura
FROM (
    SELECT ts, voltage, STATEDURATION(voltage, "GE", 240, 1m) AS dura
    FROM d1
    ORDER BY ts
) 
WHERE dura >= 30;

6.4 窗口操作限制

-- ❌ 错误：不能与窗口操作一起使用
SELECT STATEDURATION(voltage, "GE", 240, 1m) FROM d1 INTERVAL(1h);
SELECT STATEDURATION(voltage, "GE", 240, 1m) FROM d1 STATE_WINDOW(voltage);

-- ✅ 正确：单独使用
SELECT ts, voltage, STATEDURATION(voltage, "GE", 240, 1m) FROM d1;

7. 多指标监控解决方案

7.1 分步查询方案

-- 步骤1：查询电压异常持续时间
SELECT 
    ts,
    voltage,
    STATEDURATION(voltage, "GE", 240, 1m) AS high_voltage_duration_min
FROM d1
WHERE ts >= NOW() - 2h
ORDER BY ts;

-- 步骤2：查询电流过载持续时间
SELECT 
    ts,
    current,
    STATEDURATION(current, "GT", 20, 1m) AS overload_duration_min
FROM d1
WHERE ts >= NOW() - 2h
ORDER BY ts;

7.2 统计分析应用

-- 统计各设备异常持续时间的最大值
SELECT 
    tbname,
    MAX(high_voltage_duration_min) AS max_duration_min,
    COUNT(CASE WHEN high_voltage_duration_min > 0 THEN 1 END) AS abnormal_periods
FROM (
    SELECT 
        tbname,
        STATEDURATION(voltage, "GE", 240, 1m) AS high_voltage_duration_min
    FROM meters
    WHERE ts >= NOW() - 24h
    PARTITION BY tbname
    ORDER BY tbname, ts
) 
GROUP BY tbname
HAVING MAX(high_voltage_duration_min) >= 30
ORDER BY max_duration_min DESC;

8. 实际应用案例

8.1 设备维护决策

-- 基于异常持续时间制定维护计划
SELECT 
    ts,
    voltage,
    CASE 
        WHEN high_voltage_duration_min >= 120 THEN '紧急维护'
        WHEN high_voltage_duration_min >= 60 THEN '计划维护'
        WHEN high_voltage_duration_min >= 30 THEN '预防维护'
        ELSE '正常运行'
    END AS maintenance_level
FROM (
    SELECT 
        ts,
        voltage,
        STATEDURATION(voltage, "GE", 240, 1m) AS high_voltage_duration_min
    FROM d1
    WHERE ts >= NOW() - 6h
    ORDER BY ts
) 
WHERE high_voltage_duration_min >= 30;

8.2 故障模式识别

-- 基于断电持续时间识别故障类型
SELECT 
    ts,
    power,
    CASE 
        WHEN outage_duration_min >= 60 THEN '设备故障'
        WHEN outage_duration_min >= 10 THEN '线路故障'
        WHEN outage_duration_min >= 1 THEN '暂时故障'
        ELSE '正常'
    END AS fault_type
FROM (
    SELECT 
        ts,
        power,
        STATEDURATION(power, "EQ", 0, 1m) AS outage_duration_min
    FROM d1
    WHERE ts >= NOW() - 4h
    ORDER BY ts
)
WHERE outage_duration_min > 0;

9. 最佳实践建议

9.1 时间单位选择指南

• 1s（秒）：适用于高频采集数据的精确分析
• 1m（分钟）：适用于常规设备状态监控
• 1h（小时）：适用于长期趋势分析
• 1d（天）：适用于设备运行周期分析

9.2 性能优化建议

-- 推荐：限制时间范围
SELECT STATEDURATION(voltage, "GE", 240, 1m) 
FROM d1 
WHERE ts >= NOW() - 2h;

-- 推荐：选择合适的时间单位
-- 短期分析使用秒或分钟
SELECT STATEDURATION(voltage, "GE", 240, 1s) FROM d1 WHERE ts >= NOW() - 10m;
-- 长期分析使用小时
SELECT STATEDURATION(voltage, "GE", 240, 1h) FROM d1 WHERE ts >= NOW() - 7d;

9.3 报警阈值设置建议

• 电压异常分级：轻度(5-15分钟)、中度(15-30分钟)、重度(30-60分钟)、严重(>60分钟)
• 电流过载分级：轻微(1-5分钟)、中等(5-15分钟)、严重(>15分钟)
• 设备断电分级：瞬时(<1分钟)、短时(1-10分钟)、长时(>10分钟)

10. 总结

STATEDURATION 函数是智能电表监控系统中进行连续状态持续时间分析的重要工具：

主要特点

1. 时间维度分析：提供连续状态的精确持续时间统计
2. 灵活时间单位：支持秒、分钟、小时、天、周等多种时间单位
3. 单函数限制：每个 SELECT 语句只能包含一个 STATEDURATION 函数
4. 子查询支持：支持在子查询中使用，提供更灵活的查询能力
5. 超级表限制：只能使用 PARTITION BY tbname，不能按标签分区

应用价值

1. 故障分析：精确计算设备异常状态的持续时间
2. 维护决策：基于异常持续时间制定设备维护计划
3. 质量评估：评估电力质量异常的持续时间
4. 报警分级：基于异常持续时间长短实现智能报警分级

最佳实践

• 合理选择时间单位：根据数据采集频率和分析需求选择合适的时间单位
• 设置分级阈值：基于业务需求设置不同级别的持续时间阈值
• 正确使用分区：超级表查询只能使用 PARTITION BY tbname
• 善用嵌套查询：通过嵌套查询实现复杂的过滤和分析需求
• 限制查询范围：适当限制查询时间范围，提高查询性能

通过正确使用 STATEDURATION 函数，可以为智能电表系统提供强大的状态持续时间分析能力，为设备维护、故障预防和电力质量管理提供重要的数据支撑。

关于 TDengine

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