TDengine TIMETRUNCATE 函数用户使用手册
TDengine TIMETRUNCATE 函数用户使用手册
函数概述
TIMETRUNCATE 是 TDengine 中的一个时间处理标量函数，用于将时间戳按照指定的时间单位进行截断操作。该函数在时间数据聚合、分组和统计分析中非常有用，特别适用于智能电表等时序数据的分析场景。
语法
TIMETRUNCATE(expr, time_unit [, use_current_timezone])
参数说明
| 参数 | 类型 | 必需 | 说明 |
|---|---|---|---|
expr | TIMESTAMP/BIGINT/VARCHAR/NCHAR | 是 | 要截断的时间表达式 |
time_unit | 时间单位标识符 | 是 | 时间单位，不使用引号 |
use_current_timezone | INT | 否 | 是否使用当前时区（0=UTC，1=当前时区），默认为1 |
支持的时间单位
| 时间单位 | 说明 | 示例 |
|---|---|---|
1b | 纳秒 | 截断到纳秒 |
1u | 微秒 | 截断到微秒 |
1a | 毫秒 | 截断到毫秒 |
1s | 秒 | 截断到秒 |
1m | 分钟 | 截断到分钟 |
1h | 小时 | 截断到小时 |
1d | 天 | 截断到天 |
1w | 周 | 截断到周（从周四开始） |
返回值
- 返回类型：TIMESTAMP
- 精度：与当前数据库设置的时间精度一致
- 特殊情况：输入不符合时间日期格式的字符串时返回 NULL
支持的输入类型
- TIMESTAMP 类型：标准时间戳
- BIGINT 类型：Unix 时间戳
- VARCHAR/NCHAR 类型：符合 ISO8601/RFC3339 标准的日期时间格式字符串
使用示例
基础截断操作
-- 使用test数据库的智能电表数据
USE test;-- 截断到秒（注意时间单位不使用引号）
SELECT TIMETRUNCATE('2023-10-15 14:30:25.123', 1s);
-- 结果: 2023-10-15 14:30:25.000-- 截断到分钟
SELECT TIMETRUNCATE('2023-10-15 14:30:25', 1m);
-- 结果: 2023-10-15 14:30:00.000-- 截断到小时
SELECT TIMETRUNCATE('2023-10-15 14:30:25', 1h);
-- 结果: 2023-10-15 14:00:00.000-- 截断到天
SELECT TIMETRUNCATE('2023-10-15 14:30:25', 1d);
-- 结果: 2023-10-15 00:00:00.000
智能电表数据应用示例
1. 按小时统计电表数据
-- 统计每小时的平均电流和电压
SELECT TIMETRUNCATE(ts, 1h) as hour_time,AVG(current) as avg_current,AVG(voltage) as avg_voltage,COUNT(*) as data_count
FROM test.meters
WHERE ts >= '2023-10-01' AND ts < '2023-10-02'
GROUP BY TIMETRUNCATE(ts, 1h)
ORDER BY hour_time;
2. 按天分组分析电表读数
-- 统计每天各个位置的电表数据
SELECT TIMETRUNCATE(ts, 1d) as day_time,location,AVG(current) as daily_avg_current,MAX(voltage) as daily_max_voltage,MIN(voltage) as daily_min_voltage
FROM test.meters
WHERE ts >= '2023-10-01'
GROUP BY TIMETRUNCATE(ts, 1d), location
ORDER BY day_time, location;
3. 特定子表的分钟级数据统计
-- d0电表的分钟级功率分析
SELECT TIMETRUNCATE(ts, 1m) as minute_time,AVG(current * voltage) as avg_power,MAX(phase) as max_phase
FROM test.d0
WHERE ts >= NOW() - 1d
GROUP BY TIMETRUNCATE(ts, 1m)
ORDER BY minute_time;
4. 按周统计不同组别的电表数据
-- 按周统计不同groupid的电表数据
SELECT TIMETRUNCATE(ts, 1w) as week_time,groupid,COUNT(*) as weekly_readings,AVG(current) as weekly_avg_current
FROM test.meters
WHERE ts >= '2023-09-01'
GROUP BY TIMETRUNCATE(ts, 1w), groupid
ORDER BY week_time, groupid;
时区处理示例
-- 使用 UTC 时区截断（假设当前时区为 UTC+8）
SELECT TIMETRUNCATE(ts, 1d, 0) as utc_day,COUNT(*) as count
FROM test.meters
WHERE ts >= '2023-10-15' AND ts < '2023-10-16'
GROUP BY TIMETRUNCATE(ts, 1d, 0);-- 使用当前时区截断
SELECT TIMETRUNCATE(ts, 1d, 1) as local_day,COUNT(*) as cnt
FROM test.meters
WHERE ts >= '2023-10-15' AND ts < '2023-10-16'
GROUP BY TIMETRUNCATE(ts, 1d, 1);
复杂业务场景应用
1. 电表异常检测（按小时分析）
-- 检测每小时电压异常的电表
SELECT TIMETRUNCATE(ts, 1h) as hour_time,location,COUNT(*) as abnormal_count
FROM test.meters
WHERE voltage > 250 OR voltage < 200
GROUP BY TIMETRUNCATE(ts, 1h), location
HAVING COUNT(*) > 5
ORDER BY hour_time DESC;
2. 电表负载分析（按日统计）
-- 每日用电负载分析
SELECT TIMETRUNCATE(ts, 1d) as date,SUM(current * voltage) / 1000 as daily_power_kwh,AVG(current * voltage) as avg_power_w
FROM test.meters
WHERE location = 'Beijing.Chaoyang'
GROUP BY TIMETRUNCATE(ts, 1d)
ORDER BY date;
3. 多表对比分析
-- 对比不同电表同一小时的数据
SELECT TIMETRUNCATE(d0.ts, 1h) as hour_time,AVG(d0.current) as d0_avg_current,AVG(d1.current) as d1_avg_current,AVG(d0.voltage) as d0_avg_voltage,AVG(d1.voltage) as d1_avg_voltage
FROM test.d0, test.d1
WHERE TIMETRUNCATE(d0.ts, 1h) = TIMETRUNCATE(d1.ts, 1h)AND d0.ts >= '2023-10-15' AND d0.ts < '2023-10-16'AND d1.ts >= '2023-10-15' AND d1.ts < '2023-10-16'
GROUP BY TIMETRUNCATE(d0.ts, 1h)
ORDER BY hour_time;
注意事项和最佳实践
1. 语法要点
- 时间单位不使用引号：
1s、1h、1d等（这是关键区别） - 函数返回的时间戳精度与数据库设置一致
- 输入时间戳精度由查询表的精度决定
2. 时区处理要点
use_current_timezone参数仅对1d和1w时间单位有效- 默认使用当前时区进行截断（
use_current_timezone=1） - 在分析跨时区的智能电表数据时需特别注意时区设置
3. 周截断特殊性
- 周截断基于 Unix 时间戳计算（1970年1月1日为起点）
- Unix 时间戳起始于周四，因此所有周截断结果都是周四
- 这与常见的周一作为一周开始的习惯不同
4. 性能优化建议
-- 在大数据量查询中，建议在 WHERE 条件中先过滤时间范围
SELECT TIMETRUNCATE(ts, 1h) as hour_time,AVG(current) as avg_current
FROM test.meters
WHERE ts >= '2023-10-15' AND ts < '2023-10-16' -- 先过滤时间范围
GROUP BY TIMETRUNCATE(ts, 1h)
ORDER BY hour_time;
5. 错误处理
-- 无效的时间格式会返回 NULL
SELECT TIMETRUNCATE('invalid-date', 1d);
-- 结果: NULL-- 时间单位如果用引号包围会导致语法错误
SELECT TIMETRUNCATE('2023-10-15', '1s');
-- 错误: syntax error-- 正确写法（不使用引号）
SELECT TIMETRUNCATE('2023-10-15', 1s);
智能电表场景的实用技巧
1. 创建时间维度视图
-- 创建按小时聚合的电表数据视图
CREATE VIEW hourly_meter_stats AS
SELECT TIMETRUNCATE(ts, 1h) as hour,location,groupid,AVG(current) as avg_current,AVG(voltage) as avg_voltage,AVG(phase) as avg_phase,COUNT(*) as reading_count
FROM test.meters
GROUP BY TIMETRUNCATE(ts, 1h), location, groupid;
2. 定时报表查询
-- 生成月度电表使用报告
SELECT TIMETRUNCATE(ts, 1d) as date,location,SUM(current * voltage * 24) / 1000 as estimated_daily_kwh
FROM test.meters
WHERE ts >= DATE_SUB(NOW(), INTERVAL 30 DAY)
GROUP BY TIMETRUNCATE(ts, 1d), location
ORDER BY date DESC, estimated_daily_kwh DESC;
常见问题
Q1: 为什么时间单位不需要引号？
A: 根据源码分析，TIMETRUNCATE 函数的 time_unit 参数被定义为特殊的时间单位标识符，不是普通的字符串参数，因此不需要用引号包围。
Q2: 如何实现按周一开始的周截断？
A: 可以通过时间偏移来实现：
# 使用毫秒偏移（3天 = 3 * 24 * 60 * 60 * 1000 = 259200000 毫秒）
SELECT TIMETRUNCATE(ts + 259200000, 1w) - 259200000 as monday_week
FROM test.meters;
Q3: 在智能电表数据分析中，建议使用哪种时间单位？
A:
- 实时监控：使用
1m或1s - 趋势分析：使用
1h或1d - 长期统计：使用
1d或1w
Q4: 时间单位参数的语法规则是什么？
A: 时间单位参数必须是不带引号的标识符，格式为数字+单位字母，如 1s、1m、1h、1d、1w 等。
相关函数
TO_TIMESTAMP(): 字符串转时间戳TO_ISO8601(): 时间戳转 ISO8601 格式字符串TIMEDIFF(): 计算时间差NOW(): 获取当前时间戳