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'); -- 錯誤
錯誤處理
常見錯誤類型
-
格式不匹配錯誤 (
TSDB_CODE_FUNC_TO_TIMESTAMP_FAILED_FORMAT_ERR)-- 錯誤示例：格式與字符串不匹配 SELECT TO_TIMESTAMP('2023-10-15', 'YYYY/MM/DD'); -
時間戳錯誤 (
TSDB_CODE_FUNC_TO_TIMESTAMP_FAILED_TS_ERR)-- 錯誤示例：非法的時間值 SELECT TO_TIMESTAMP('2023-13-40', 'YYYY-MM-DD'); -
不支持的格式 (
TSDB_CODE_FUNC_TO_TIMESTAMP_FAILED_NOT_SUPPORTED)-- 錯誤示例：使用了不支持的格式標識符 SELECT TO_TIMESTAMP('2023-10-15', 'YYYY-QQ-DD');
性能優化建議
- 預編譯格式字符串: 相同的格式字符串會被緩存，重復使用時性能更好
- 避免過長的格式字符串: 格式字符串有最大長度限制 (4096 字符)
- 批量處理: 在處理大量數據時，盡量使用批量操作而不是逐行轉換
與其他時間函數的關系
-- 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 中處理時間字符串轉換的核心工具，支持豐富的格式選項和容錯機制。合理使用該函數可以有效處理各種時間數據導入、清洗和轉換需求。在使用時需要特別注意精度設置、時區處理和格式匹配，以確保數據的準確性和一致性。
)
