TDengine 数学函数 ATAN() 用户手册
根据您提供的源码和测试用例,我来为 ATAN 函数编写完整的用户手册:
ATAN
ATAN(expr)
功能说明
返回指定字段的反正切值(单位:弧度)。
返回结果类型
DOUBLE。
适用数据类型
数值类型(TINYINT、SMALLINT、INT、BIGINT、FLOAT、DOUBLE 及其无符号类型)。
嵌套子查询支持
适用于内层查询和外层查询。
适用于
表和超级表。
使用说明
- 若
expr为 NULL,返回 NULL。 - 输入值可以是任意实数,没有范围限制。
- 返回值的范围为 (-π/2, π/2)(约 -1.5708 到 1.5708)。
- 只能与普通列、选择(Selection)、投影(Projection)函数一起使用,不能与聚合(Aggregation)函数一起使用。
使用示例
假设有以下智能电表表结构:
CREATE DATABASE power;
USE power;CREATE STABLE meters (ts TIMESTAMP,current FLOAT,voltage INT,phase FLOAT,power_factor FLOAT
) TAGS (location VARCHAR(64),groupId INT
);CREATE TABLE d1001 USING meters TAGS ('California.SanFrancisco', 1);
CREATE TABLE d1002 USING meters TAGS ('California.LosAngeles', 2);
基础示例
示例 1: 常量计算
taos> SELECT ATAN(0);atan(0) |
=========================0.000000000000000 |taos> SELECT ATAN(1);atan(1) |
=========================0.785398163397448 |taos> SELECT ATAN(-1);atan(-1) |
=========================-0.785398163397448 |taos> SELECT ATAN(1000);atan(1000) |
=========================1.569796326794897 |
示例 2: NULL 值处理
taos> SELECT ATAN(NULL);atan(null) |
=========================NULL |
示例 3: 不同数值类型
-- 整数类型
taos> SELECT ATAN(5);atan(5) |
=========================1.373400766945016 |-- 浮点类型
taos> SELECT ATAN(0.5);atan(0.5) |
=========================0.463647609000806 |-- 负数
taos> SELECT ATAN(-10);atan(-10) |
=========================-1.471127674303735 |
智能电表场景示例
示例 4: 计算电流与电压比值的反正切
-- 插入测试数据
INSERT INTO d1001 VALUES ('2018-10-03 14:38:05.000', 10.3, 220, 0.31, 0.95),('2018-10-03 14:38:15.000', 12.6, 220, 0.33, 0.92),('2018-10-03 14:38:16.800', 8.5, 221, 0.32, 0.90);-- 计算电流与电压比值的反正切
taos> SELECT ts, current, voltage, ATAN(current/voltage) AS atan_ratioFROM d1001;ts | current | voltage | atan_ratio |
====================================================================2018-10-03 14:38:05 | 10.30000 | 220 | 0.046773011956 |2018-10-03 14:38:15 | 12.60000 | 220 | 0.057218473193 |2018-10-03 14:38:16 | 8.50000 | 221 | 0.038454258977 |
示例 5: 转换为角度制
-- 将弧度转换为角度 (弧度 × 180 / π)
taos> SELECT ts, phase,ATAN(phase) AS phase_radian,ATAN(phase) * 180 / 3.14159265359 AS phase_degreeFROM d1001;ts | phase | phase_radian | phase_degree |
====================================================================2018-10-03 14:38:05 | 0.310000 | 0.300691 | 17.223 |2018-10-03 14:38:15 | 0.330000 | 0.318748 | 18.261 |2018-10-03 14:38:16 | 0.320000 | 0.309678 | 17.742 |
示例 6: 计算相位差的反正切
-- 计算两个相邻时间点相位的反正切变化
taos> SELECT ts,phase,ATAN(phase) AS current_atan,LAG(ATAN(phase), 1) OVER (ORDER BY ts) AS prev_atan,ATAN(phase) - LAG(ATAN(phase), 1) OVER (ORDER BY ts) AS atan_diffFROM d1001ORDER BY ts;
示例 7: 嵌套使用
-- 多层嵌套
taos> SELECT ATAN(ATAN(ATAN(1)));atan(atan(atan(1))) |
======================0.615363722520 |-- 与其他三角函数组合
taos> SELECT phase,ATAN(phase) AS atan_phase,TAN(ATAN(phase)) AS tan_atan_phase,ABS(phase - TAN(ATAN(phase))) AS diffFROM d1001;
示例 8: 在 WHERE 子句中使用
-- 过滤反正切值大于特定值的数据
taos> SELECT ts, phase, ATAN(phase) FROM d1001 WHERE ATAN(phase) > 0.31;ts | phase | atan(phase) |
====================================================2018-10-03 14:38:15 | 0.330000 | 0.318748 |2018-10-03 14:38:16 | 0.320000 | 0.309678 |
示例 9: 按设备分组统计
-- 统计各地区相位反正切的平均值
taos> SELECT location,AVG(ATAN(phase)) AS avg_atan_phase,AVG(ATAN(phase)) * 180 / 3.14159265359 AS avg_degreeFROM metersGROUP BY location;location | avg_atan_phase | avg_degree |
===============================================================California.SanFrancisco | 0.309706 | 17.742 |California.LosAngeles | 0.298234 | 17.085 |
示例 10: 时间窗口统计
-- 按小时统计相位反正切的变化
taos> SELECT _wstart AS time_window,location,AVG(ATAN(phase)) * 180 / 3.14159265359 AS avg_phase_degree,MAX(ATAN(phase)) * 180 / 3.14159265359 AS max_phase_degreeFROM metersWHERE ts >= NOW - 1dINTERVAL(1h)GROUP BY location;
实际生产场景应用
场景 1: 电力系统 - 阻抗角计算
-- 在电力系统中,阻抗角 θ = arctan(X/R)
-- 其中 X 为电抗,R 为电阻
SELECT tbname,ts,current,voltage,ATAN(current * 0.1 / voltage * 0.01) * 180 / 3.14159265359 AS impedance_angle
FROM meters
WHERE ts >= NOW - 1h
ORDER BY impedance_angle DESC
LIMIT 10;
场景 2: 信号处理 - 相位角分析
-- 分析信号相位角的分布情况
SELECT location,COUNT(*) AS total_samples,AVG(ATAN(phase)) * 180 / 3.14159265359 AS avg_phase_angle,STDDEV(ATAN(phase)) * 180 / 3.14159265359 AS phase_stddev,CASE WHEN AVG(ATAN(phase)) * 180 / 3.14159265359 < 15 THEN '低相位'WHEN AVG(ATAN(phase)) * 180 / 3.14159265359 < 30 THEN '中相位'ELSE '高相位'END AS phase_category
FROM meters
WHERE ts >= NOW - 7d
GROUP BY location;
场景 3: 异常检测 - 相位突变识别
-- 检测相位角突然变化超过阈值的异常情况
SELECT tbname,ts,phase,ATAN(phase) * 180 / 3.14159265359 AS current_angle,LAG(ATAN(phase) * 180 / 3.14159265359, 1) OVER (PARTITION BY tbname ORDER BY ts) AS prev_angle,ABS(ATAN(phase) * 180 / 3.14159265359 - LAG(ATAN(phase) * 180 / 3.14159265359, 1) OVER (PARTITION BY tbname ORDER BY ts)) AS angle_change
FROM meters
WHERE ts >= NOW - 1d
HAVING angle_change > 5
ORDER BY angle_change DESC;
场景 4: 趋势分析 - 斜率计算
-- 计算数据变化的斜率并转换为角度
SELECT tbname,_wstart AS time_window,AVG(current) AS avg_current,ATAN((MAX(current) - MIN(current)) / (CAST(MAX(ts) - MIN(ts) AS DOUBLE) / 1000)) * 180 / 3.14159265359 AS change_slope_angle
FROM meters
WHERE ts >= NOW - 1d
INTERVAL(10m)
GROUP BY tbname;
注意事项
- ATAN 函数接受任意实数作为输入,没有范围限制,这与 ASIN 和 ACOS 不同。
- 返回值为弧度制,范围在 (-π/2, π/2)。如需转换为角度,需乘以 180/π (约 57.2958)。
- 当输入值趋向无穷大时,ATAN 的返回值趋向 ±π/2 (约 ±1.5708)。
- 不能与聚合函数(如 SUM、AVG)直接组合使用在同一层级,需使用子查询。
- 对于 NULL 值,函数返回 NULL,不会报错。
- 浮点数计算可能存在精度问题,在进行相等性比较时需要注意。
- ATAN(0) 精确返回 0。
性能说明
- ATAN 函数是标量函数,对每一行数据独立计算。
- 在大数据量场景下,建议配合索引和合适的 WHERE 过滤条件使用。
- 嵌套使用会增加计算复杂度,建议避免过深的嵌套。
相关函数
- ACOS: 反余弦函数,输入范围限制为 [-1, 1]
- ASIN: 反正弦函数,输入范围限制为 [-1, 1]
- TAN: 正切函数,ATAN 的反函数
- SIN: 正弦函数
- COS: 余弦函数
- DEGREES: 将弧度转换为角度
- RADIANS: 将角度转换为弧度
数学关系
TAN(ATAN(x)) = x(对所有实数 x)ATAN(TAN(x)) = x(当 x ∈ (-π/2, π/2))ATAN(0) = 0ATAN(1) = π/4 ≈ 0.7854ATAN(-1) = -π/4 ≈ -0.7854- 当
x → +∞时,ATAN(x) → π/2 - 当
x → -∞时,ATAN(x) → -π/2
关于 TDengine
TDengine 专为物联网IoT平台、工业大数据平台设计。其中，TDengine TSDB 是一款高性能、分布式的时序数据库（Time Series Database），同时它还带有内建的缓存、流式计算、数据订阅等系统功能；TDengine IDMP 是一款AI原生工业数据管理平台，它通过树状层次结构建立数据目录，对数据进行标准化、情景化，并通过 AI 提供实时分析、可视化、事件管理与报警等功能。