当前位置：首页 > news >正文

TDengine 比较函数 IF 用户手册

news 2025/10/5 9:50:13

在这里插入图片描述

IF

1. 函数概述

项目	说明
函数名称	IF
功能	按行评估条件表达式，条件为真返回第二参数，条件为假或 NULL 返回第三参数。
语法	`IF(cond_expr, true_expr, false_expr)`
返回类型	由 `true_expr` 与 `false_expr` 的可兼容类型推导（保持原类型精度）。
适用范围	表与超级表，支持 SELECT、WHERE、GROUP BY、PARTITION BY、INTERVAL、STATE_WINDOW、SESSION_WINDOW 等上下文。
支持版本	TDengine TSDB v3.3.8.0 及以上

2. 参数说明

参数	描述
cond_expr	任意可转为布尔的表达式：数值非 0 为真，0/NULL 为假；布尔类型按 true/false 处理。
true_expr	条件为真时的返回值，可为列、常量、表达式或聚合；需与 `false_expr` 可统一类型。
false_expr	条件为假（含 NULL）时的返回值，可为列、常量、表达式或聚合；与 `true_expr` 保持兼容。

3. 行为细则

条件或选中分支为 NULL 时返回 NULL。
支持嵌套 IF 与聚合函数，但需满足 SQL 聚合规则。
可在窗口与分区语句中使用构造分组键。
不允许将 GEOMETRY、JSON 与普通标量类型混用，否则报错。

4. 智能电表表结构

CREATE STABLE meters (ts TIMESTAMP,voltage FLOAT,current FLOAT,power FLOAT
) TAGS (groupid INT,location VARCHAR(64)
);

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

TDengine 逐行计算 cond_expr，判定布尔值；若真取 true_expr 结果，若假或 NULL 取 false_expr 结果。
返回列类型取两分支的公共类型（例如 INT 与 DOUBLE 推导为 DOUBLE；TIMESTAMP 保留时间戳类型）。
在 GROUP BY/窗口语句中，先聚合后计算 IF，输出每组或每窗口的单行结果。

6. SQL 示例与意义

-- 1) SELECT 中生成电压等级标签，便于直观检查
SELECTts,voltage,IF(voltage >= 240, 'OVER_VOLT', 'NORMAL') AS voltage_level
FROM meters
WHERE location = 'East.Park'
ORDER BY ts;

-- 2) WHERE 过滤高负荷记录，缩小检索范围
SELECT *
FROM meters
IF(power > 5000, 1, 0) = 1;

-- 3) GROUP BY 中构造分组键，对不同电流区间汇总能耗
SELECTIF(current >= 30, 'HIGH', 'LOW') AS current_band,SUM(power) AS total_power
FROM meters
PARTITION BY tbname

-- 4) INTERVAL 窗口判断每分钟告警状态
SELECT_wstart,IF(MAX(voltage) > 250, 'ALARM', 'OK') AS minute_flag
FROM meters
INTERVAL(1m);

-- 5)  where 从句中使用
SELECTIF(current > 25, 'OVER_CURRENT', 'SAFE') AS state_id 
FROM meters 
WHERE IF(current > 25, 1, 0);

7. 实际场景示例

异常告警生成：通过 IF 将电压、电流瞬时值转为“正常/预警/告警”标签，供监控看板或短信系统触发不同级别的通知。
能耗报表：在按小时聚合报表中使用 IF 按高负荷/低负荷区间统计功率，为节能分析提供依据。
维护优先级排序：利用 IF 在 ORDER BY 中计算权重，把需优先巡检的设备排在前面。
数据清洗与补值：对 NULL 电流使用 IF 填充默认值，或标记为异常行，辅助后续数据补录。

8. 常见错误与排查

问题	处理建议
分支类型不兼容（如 GEOMETRY 与 FLOAT 混用）	调整分支使其返回相同或可隐式转换的标量类型。
在 WHERE 中直接引用含聚合的 IF 导致语法错误	使用子查询先计算聚合，再在外层 WHERE 过滤。
条件使用无法转换的字符串（如 `IF('a', ...)` 返回 NULL）	显式 CAST 或改用布尔/数值条件表达式。
SELECT 同时包含聚合和未分组列且使用 IF 引起分组错误	将未分组列加入 GROUP BY 或重写查询结构。

该手册基于 test_if.py 测试用例及内核行为整理，可直接纳入 22-function.md。