网站导航
> 技术文档 > TDengine 转化函数 TO_TIMESTAMP 用户手册

TDengine 转化函数 TO_TIMESTAMP 用户手册

网友: 技术文档 2025-07-26 20:34:46

TDengine 转化函数 TO_TIMESTAMP 用户手册

TDengine TO_TIMESTAMP 函数用户使用手册

函数概述

TO_TIMESTAMP 是 TDengine 中的标量函数，用于将字符串按照指定格式转换为时间戳。该函数在数据导入、时间格式转换、以及处理各种时间字符串格式时非常有用。

语法

TO_TIMESTAMP(ts_str_literal, format_str_literal)

参数说明

  • ts_str_literal: 时间字符串，VARCHAR 类型
  • format_str_literal: 格式字符串，VARCHAR 类型，定义了时间字符串的格式

返回值

  • 数据类型: TIMESTAMP
  • 精度: 与查询表的时间精度一致，若未指定表则默认为毫秒精度

版本支持

  • 起始版本: v3.2.2.0
  • 适用范围: 表和超级表
  • 嵌套查询: 支持内层查询和外层查询

格式字符串说明

支持的格式标识符

基于源码分析，TDengine 支持以下格式标识符：

年份格式
  • YYYY/yyyy: 4位年份 (如: 2023)
  • YYY/yyy: 3位年份 (如: 023)
  • YY/yy: 2位年份 (如: 23)
  • Y/y: 1位年份 (如: 3)
月份格式
  • MM/mm: 2位月份数字 (01-12)
  • MONTH/month: 完整月份名称 (大小写不敏感)
  • MON/mon: 缩写月份名称 (大小写不敏感)
  • Month: 首字母大写的月份名称
日期格式
  • DD/dd: 2位日期 (01-31)
  • DDD/ddd: 一年中的第几天 (001-366)
  • D/d: 1位日期 (1-31)
  • DAY/day: 完整星期名称
  • DY/dy: 缩写星期名称
时间格式
  • HH24/hh24: 24小时制小时 (00-23)
  • HH12/hh12: 12小时制小时 (01-12)
  • HH/hh: 小时 (默认24小时制)
  • MI/mi: 分钟 (00-59)
  • SS/ss: 秒 (00-59)
亚秒精度格式
  • MS/ms: 毫秒 (000-999)
  • US/us: 微秒 (000000-999999)
  • NS/ns: 纳秒 (000000000-999999999)
上午/下午标识
  • AM/am/A.M./a.m.: 上午标识
  • PM/pm/P.M./p.m.: 下午标识
时区格式
  • TZH/tzh: 时区小时偏移

使用场景详解

1. 数据导入场景

当从外部系统导入数据时，时间格式可能多种多样：

-- 从 CSV 文件导入标准 ISO 格式时间SELECT TO_TIMESTAMP(\'2023-10-15 14:30:25\', \'YYYY-MM-DD HH24:MI:SS\') as ts;-- 导入美式日期格式SELECT TO_TIMESTAMP(\'10/15/2023 2:30:25 PM\', \'MM/DD/YYYY HH12:MI:SS PM\') as ts;-- 导入欧式日期格式SELECT TO_TIMESTAMP(\'15.10.2023 14:30:25\', \'DD.MM.YYYY HH24:MI:SS\') as ts;

2. 日志分析场景

处理不同系统的日志时间格式：

-- Apache 日志格式SELECT TO_TIMESTAMP(\'15/Oct/2023:14:30:25\', \'DD/MON/YYYY:HH24:MI:SS\') as log_time;-- 应用程序日志格式SELECT TO_TIMESTAMP(\'2023-10-15T14:30:25.123\', \'YYYY-MM-DDTHH24:MI:SS.MS\') as app_time;-- 系统日志格式SELECT TO_TIMESTAMP(\'Oct 15 14:30:25\', \'MON DD HH24:MI:SS\') as sys_time;

3. 数据清洗场景

清理和标准化不规范的时间数据：

-- 处理缺少前导零的时间SELECT TO_TIMESTAMP(\'2023-1-5 9:5:5\', \'YYYY-MM-DD HH24:MI:SS\') as clean_time;-- 处理包含多余空格的时间SELECT TO_TIMESTAMP(\' 2023 年 - 10 月 - 15 日 \', \'YYYY 年-MM月-DD日\') as chinese_time;

4. 时区处理场景

处理带时区信息的时间字符串：

-- 处理带时区偏移的时间SELECT TO_TIMESTAMP(\'2023-10-15 14:30:25+08\', \'YYYY-MM-DD HH24:MI:SS+TZH\') as tz_time;-- 建议：为避免时区混乱，建议在时间字符串中包含时区信息SELECT TO_TIMESTAMP(\'2023-10-15 14:30:25+08:00\', \'YYYY-MM-DD HH24:MI:SS\') as recommended;

5. 高精度时间处理场景

处理需要高精度的时间数据：

-- 纳秒精度时间戳 (需要在纳秒精度的表中查询)SELECT TO_TIMESTAMP(\'2023-10-15 14:30:25.123456789\', \'YYYY-MM-DD HH24:MI:SS.NS\') FROM nano_precision_table LIMIT 1;-- 同时指定毫秒、微秒、纳秒SELECT TO_TIMESTAMP(\'2023-10-15 14:30:25.123.000456.000000789\',  \'YYYY-MM-DD HH24:MI:SS.MS.US.NS\') FROM nano_precision_table LIMIT 1;

实用示例

基础用法示例

-- 1. 标准 ISO 8601 格式SELECT TO_TIMESTAMP(\'2023-10-15 14:30:25\', \'YYYY-MM-DD HH24:MI:SS\');-- 2. 带毫秒的时间SELECT TO_TIMESTAMP(\'2023-10-15 14:30:25.123\', \'YYYY-MM-DD HH24:MI:SS.MS\');-- 3. 12小时制格式SELECT TO_TIMESTAMP(\'2023-10-15 2:30:25 PM\', \'YYYY-MM-DD HH12:MI:SS PM\');-- 4. 月份名称格式SELECT TO_TIMESTAMP(\'15-October-2023 14:30:25\', \'DD-MONTH-YYYY HH24:MI:SS\');

容错机制示例

-- 格式串容错：多余的字符会被忽略SELECT TO_TIMESTAMP(\'200101/2\', \'yyyyMM1/dd\');-- 空格容错：多余的空格会被自动忽略 SELECT TO_TIMESTAMP(\' 23 年 - 1 月 - 01 日 \', \'yy 年-MM月-dd日\');-- 数字位数容错：不足两位的数字也能正确解析SELECT TO_TIMESTAMP(\'2023-1-1\', \'YYYY-MM-DD\');

高级应用示例

-- 1. 在数据插入中使用INSERT INTO sensor_data (ts, temperature) VALUES (TO_TIMESTAMP(\'2023-10-15 14:30:25\', \'YYYY-MM-DD HH24:MI:SS\'), 25.6);-- 2. 在 WHERE 条件中使用SELECT * FROM sensor_data WHERE ts >= TO_TIMESTAMP(\'2023-10-15 00:00:00\', \'YYYY-MM-DD HH24:MI:SS\');-- 3. 在聚合查询中使用SELECT COUNT(*) FROM sensor_data WHERE ts BETWEEN TO_TIMESTAMP(\'2023-10-15 00:00:00\', \'YYYY-MM-DD HH24:MI:SS\') AND TO_TIMESTAMP(\'2023-10-15 23:59:59\', \'YYYY-MM-DD HH24:MI:SS\');-- 4. 与其他时间函数结合使用SELECT TO_CHAR(TO_TIMESTAMP(\'2023-10-15 14:30:25\', \'YYYY-MM-DD HH24:MI:SS\'), \'YYYY年MM月DD日\') as formatted_date;

注意事项和最佳实践

1. 精度处理

-- 注意：输出精度取决于查询的表-- 在毫秒表中查询，纳秒部分会被截断SELECT TO_TIMESTAMP(\'2023-10-15 14:30:25.123456789\', \'YYYY-MM-DD HH24:MI:SS.NS\') FROM millisecond_table LIMIT 1; -- 结果：2023-10-15 14:30:25.123-- 在纳秒表中查询，保留完整精度SELECT TO_TIMESTAMP(\'2023-10-15 14:30:25.123456789\', \'YYYY-MM-DD HH24:MI:SS.NS\') FROM nanosecond_table LIMIT 1; -- 结果：2023-10-15 14:30:25.123456789

2. 字段覆盖规则

-- 如果同一字段被指定多次，后面的会覆盖前面的SELECT TO_TIMESTAMP(\'2023-22-10-10\', \'yyyy-yy-MM-dd\'); -- 年份结果是 2022

3. 时区处理建议

-- 推荐：明确指定时区信息SELECT TO_TIMESTAMP(\'2023-10-15 14:30:25+08:00\', \'YYYY-MM-DD HH24:MI:SS\');-- 避免：依赖默认时区可能导致混乱SELECT TO_TIMESTAMP(\'2023-10-15 14:30:25\', \'YYYY-MM-DD HH24:MI:SS\');

4. 12小时制使用

-- 使用 AM/PM 时，小时必须是 12 小时制 (01-12)SELECT TO_TIMESTAMP(\'2023-10-15 02:30:25 PM\', \'YYYY-MM-DD HH12:MI:SS PM\'); -- 正确SELECT TO_TIMESTAMP(\'2023-10-15 14:30:25 PM\', \'YYYY-MM-DD HH12:MI:SS PM\'); -- 错误

错误处理

常见错误类型

  1. 格式不匹配错误 (TSDB_CODE_FUNC_TO_TIMESTAMP_FAILED_FORMAT_ERR)

    -- 错误示例：格式与字符串不匹配SELECT TO_TIMESTAMP(\'2023-10-15\', \'YYYY/MM/DD\');

  2. 时间戳错误 (TSDB_CODE_FUNC_TO_TIMESTAMP_FAILED_TS_ERR)

    -- 错误示例：非法的时间值SELECT TO_TIMESTAMP(\'2023-13-40\', \'YYYY-MM-DD\');

  3. 不支持的格式 (TSDB_CODE_FUNC_TO_TIMESTAMP_FAILED_NOT_SUPPORTED)

    -- 错误示例：使用了不支持的格式标识符SELECT TO_TIMESTAMP(\'2023-10-15\', \'YYYY-QQ-DD\');

性能优化建议

  1. 预编译格式字符串: 相同的格式字符串会被缓存，重复使用时性能更好
  2. 避免过长的格式字符串: 格式字符串有最大长度限制 (4096 字符)
  3. 批量处理: 在处理大量数据时，尽量使用批量操作而不是逐行转换

与其他时间函数的关系

-- TO_TIMESTAMP 与 TO_CHAR 是逆操作SELECT TO_CHAR(TO_TIMESTAMP(\'2023-10-15\', \'YYYY-MM-DD\'), \'YYYY年MM月DD日\');-- 与 NOW()、TODAY() 结合使用SELECT TO_TIMESTAMP(\'14:30:25\', \'HH24:MI:SS\') + (TODAY() - TO_TIMESTAMP(\'00:00:00\', \'HH24:MI:SS\'));-- 与 TIMEDIFF 结合计算时间差SELECT TIMEDIFF(NOW(), TO_TIMESTAMP(\'2023-10-15 14:30:25\', \'YYYY-MM-DD HH24:MI:SS\'));

总结

TO_TIMESTAMP 函数是 TDengine 中处理时间字符串转换的核心工具，支持丰富的格式选项和容错机制。合理使用该函数可以有效处理各种时间数据导入、清洗和转换需求。在使用时需要特别注意精度设置、时区处理和格式匹配，以确保数据的准确性和一致性。

网络标签：

相关问题