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 接口和國際化應用的時間數據。選擇使用哪個函數主要取決于輸入數據的格式標準化程度和應用場景的具體需求。
