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

支持的输入类型

1. TIMESTAMP 类型：标准时间戳
2. BIGINT 类型：Unix 时间戳
3. 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(): 获取当前时间戳