TDengine TO_UNIXTIMESTAMP 函数用户使用手册
函数概述
TO_UNIXTIMESTAMP 是 TDengine 中的标量函数，用于将符合 ISO8601/RFC3339 标准的日期时间字符串转换为 Unix 时间戳。与 TO_TIMESTAMP 不同，该函数专门处理标准格式的时间字符串，无需指定格式字符串。
语法
TO_UNIXTIMESTAMP(expr [, return_timestamp])
参数说明
- expr: 日期时间字符串，VARCHAR 或 NCHAR 类型，必须符合 ISO8601/RFC3339 标准
- return_timestamp: 可选参数，指定返回值类型
0: 返回 BIGINT 类型的时间戳（默认值）1: 返回 TIMESTAMP 类型的时间戳
返回值
- 数据类型: BIGINT 或 TIMESTAMP（根据 return_timestamp 参数决定）
- 精度: 与当前数据库设置的时间精度一致
版本支持
- 适用范围: 表和超级表
- 嵌套查询: 支持内层查询和外层查询
支持的时间格式
ISO8601/RFC3339 标准格式
基于源码分析，TO_UNIXTIMESTAMP 支持以下标准时间格式：
基本格式
-- 基本日期时间格式
'2023-10-15T14:30:25'
'2023-10-15 14:30:25'-- 带毫秒精度
'2023-10-15T14:30:25.123'
'2023-10-15 14:30:25.123'-- 带微秒精度
'2023-10-15T14:30:25.123456'
'2023-10-15 14:30:25.123456'-- 带纳秒精度
'2023-10-15T14:30:25.123456789'
'2023-10-15 14:30:25.123456789'
时区格式
-- UTC 时区标识
'2023-10-15T14:30:25Z'
'2023-10-15T14:30:25z'-- 正时区偏移
'2023-10-15T14:30:25+08:00'
'2023-10-15T14:30:25+0800'
'2023-10-15T14:30:25+08'-- 负时区偏移
'2023-10-15T14:30:25-05:00'
'2023-10-15T14:30:25-0500'
'2023-10-15T14:30:25-05'
使用场景详解
1. 标准时间字符串转换
处理来自标准系统的时间数据：
-- 转换 ISO8601 格式时间为 BIGINT 时间戳
SELECT TO_UNIXTIMESTAMP('2023-10-15T14:30:25Z') as unix_ts;-- 转换为 TIMESTAMP 类型
SELECT TO_UNIXTIMESTAMP('2023-10-15T14:30:25Z', 1) as timestamp_ts;-- 处理带毫秒的时间
SELECT TO_UNIXTIMESTAMP('2023-10-15T14:30:25.123+08:00') as precise_ts;
2. API 数据处理
处理来自 REST API 或 JSON 的时间数据：
-- 处理 JavaScript Date.toISOString() 格式
SELECT TO_UNIXTIMESTAMP('2023-10-15T14:30:25.123Z') as js_time;-- 处理服务器日志的 RFC3339 格式
SELECT TO_UNIXTIMESTAMP('2023-10-15T14:30:25.123456+08:00') as server_time;
3. 数据同步场景
在不同系统间同步时间数据：
-- 从外部系统同步数据
INSERT INTO sync_table (ts, data)
SELECT TO_UNIXTIMESTAMP(time_str, 1), value
FROM external_data;-- 批量处理时间转换
SELECT TO_UNIXTIMESTAMP(iso_time, 1) as converted_time,sensor_value
FROM import_table
WHERE iso_time IS NOT NULL;
4. 时区标准化
将不同时区的时间标准化：
-- 处理来自不同时区的数据
SELECT TO_UNIXTIMESTAMP('2023-10-15T14:30:25+08:00', 1) as beijing_time,TO_UNIXTIMESTAMP('2023-10-15T06:30:25Z', 1) as utc_time,TO_UNIXTIMESTAMP('2023-10-15T01:30:25-05:00', 1) as ny_time;
实用示例
基础用法示例
-- 1. 基本转换（返回 BIGINT）
SELECT TO_UNIXTIMESTAMP('2023-10-15T14:30:25') as bigint_result;-- 2. 返回 TIMESTAMP 类型
SELECT TO_UNIXTIMESTAMP('2023-10-15T14:30:25', 1) as timestamp_result;-- 3. 处理 UTC 时间
SELECT TO_UNIXTIMESTAMP('2023-10-15T14:30:25Z') as utc_timestamp;-- 4. 处理带时区偏移的时间
SELECT TO_UNIXTIMESTAMP('2023-10-15T14:30:25+08:00') as tz_timestamp;
高级应用示例
-- 1. 在数据插入中使用
INSERT INTO events (ts, event_type, data)
VALUES (TO_UNIXTIMESTAMP('2023-10-15T14:30:25.123Z', 1), 'user_login', 'user123'
);-- 2. 在查询条件中使用
SELECT * FROM events
WHERE ts >= TO_UNIXTIMESTAMP('2023-10-15T00:00:00Z', 1)AND ts < TO_UNIXTIMESTAMP('2023-10-16T00:00:00Z', 1);-- 3. 数据类型转换
SELECT iso_time_str,TO_UNIXTIMESTAMP(iso_time_str, 0) as bigint_ts,TO_UNIXTIMESTAMP(iso_time_str, 1) as timestamp_ts
FROM source_table;-- 4. 与聚合函数结合
SELECT COUNT(*) as event_count,MIN(TO_UNIXTIMESTAMP(time_str, 1)) as first_event,MAX(TO_UNIXTIMESTAMP(time_str, 1)) as last_event
FROM log_table
WHERE time_str IS NOT NULL;
错误处理示例
-- 处理可能的转换失败（返回 NULL）
SELECT time_str,TO_UNIXTIMESTAMP(time_str, 1) as converted_time,CASE WHEN TO_UNIXTIMESTAMP(time_str, 1) IS NULL THEN 'Invalid format' ELSE 'Valid' END as status
FROM input_table;
TO_TIMESTAMP 与 TO_UNIXTIMESTAMP 的区别
功能对比
| 特性 | TO_TIMESTAMP | TO_UNIXTIMESTAMP |
|---|---|---|
| 格式要求 | 需要指定格式字符串 | 固定 ISO8601/RFC3339 格式 |
| 输入参数 | 2个参数（时间字符串+格式字符串） | 1-2个参数（时间字符串+可选返回类型） |
| 返回类型 | 固定返回 TIMESTAMP | 可选择 BIGINT 或 TIMESTAMP |
| 格式灵活性 | 支持自定义格式 | 仅支持标准格式 |
| 使用复杂度 | 需要了解格式字符串 | 使用简单，无需格式字符串 |
| 容错机制 | 较强的容错能力 | 严格按标准格式解析 |
使用场景选择
使用 TO_TIMESTAMP 的情况：
-- 1. 非标准格式的时间字符串
SELECT TO_TIMESTAMP('2023年10月15日 14:30:25', 'YYYY年MM月DD日 HH24:MI:SS');-- 2. 自定义分隔符格式
SELECT TO_TIMESTAMP('15/10/2023 14:30:25', 'DD/MM/YYYY HH24:MI:SS');-- 3. 需要处理多种格式的数据
SELECT TO_TIMESTAMP(time_str, format_str) FROM mixed_format_table;
使用 TO_UNIXTIMESTAMP 的情况：
-- 1. 标准 ISO8601 格式数据
SELECT TO_UNIXTIMESTAMP('2023-10-15T14:30:25Z');-- 2. API 接口返回的标准时间
SELECT TO_UNIXTIMESTAMP(api_timestamp, 1) FROM api_data;-- 3. 需要同时获得 BIGINT 和 TIMESTAMP 类型
SELECT TO_UNIXTIMESTAMP(iso_time, 0) as unix_bigint,TO_UNIXTIMESTAMP(iso_time, 1) as unix_timestamp
FROM standard_time_table;
注意事项和最佳实践
1. 格式严格性
-- 正确：符合标准格式
SELECT TO_UNIXTIMESTAMP('2023-10-15T14:30:25Z');-- 错误：非标准格式会返回 NULL
SELECT TO_UNIXTIMESTAMP('2023年10月15日'); -- 返回 NULL
2. 时区处理
-- 推荐：明确指定时区信息
SELECT TO_UNIXTIMESTAMP('2023-10-15T14:30:25+08:00');-- 注意：无时区信息时使用系统默认时区
SELECT TO_UNIXTIMESTAMP('2023-10-15T14:30:25');
3. 返回类型选择
-- 需要进行数值计算时使用 BIGINT
SELECT TO_UNIXTIMESTAMP('2023-10-15T14:30:25Z', 0) * 1000 as milliseconds;-- 需要时间戳功能时使用 TIMESTAMP
SELECT TO_UNIXTIMESTAMP('2023-10-15T14:30:25Z', 1) as ts_column;
4. NULL 值处理
-- 安全的 NULL 值处理
SELECT COALESCE(TO_UNIXTIMESTAMP(time_str, 1), NOW()) as safe_timestamp
FROM unreliable_source;
性能优化建议
- 批量处理: 在处理大量数据时，充分利用函数的向量化处理能力
- 类型选择: 根据后续使用需求选择合适的返回类型，避免不必要的类型转换
- 预先验证: 对于不可靠的数据源，建议先验证时间格式的有效性
与其他时间函数的关系
-- 与 TO_TIMESTAMP 的转换关系
SELECT TO_UNIXTIMESTAMP('2023-10-15T14:30:25Z', 1) as from_unixtimestamp,TO_TIMESTAMP('2023-10-15 14:30:25', 'YYYY-MM-DD HH24:MI:SS') as from_timestamp;-- 与 TO_CHAR 的配合使用
SELECT TO_CHAR(TO_UNIXTIMESTAMP('2023-10-15T14:30:25Z', 1), 'YYYY-MM-DD HH24:MI:SS');-- 与时间计算函数配合
SELECT TIMEDIFF(NOW(), TO_UNIXTIMESTAMP('2023-10-15T14:30:25Z', 1));
总结
TO_UNIXTIMESTAMP 函数是 TDengine 中处理标准时间格式转换的专用工具，专门用于处理符合 ISO8601/RFC3339 标准的时间字符串。该函数使用简单，无需格式字符串，但要求输入严格符合标准格式。适用于处理来自标准系统、API 接口和国际化应用的时间数据。选择使用哪个函数主要取决于输入数据的格式标准化程度和应用场景的具体需求。
