TO_TIME - MaxCompute

TO_TIME函數用於將不同類型和格式的時間資料，構造或轉換為以微秒為單位，用BIGINT類型表示的時間值。

命令格式

TO_TIME函數支援以下四種簽名格式，請根據不同使用需求選擇不同的函數簽名。

簽名1：將時間格式的String類型輸入value，按照指定的format格式解析，並返回以微秒為單位用BIGINT類型表示的時間值。
```
BIGINT TO_TIME(STRING <value>, STRING <format>)

-- 標準樣本。
-- 返回48273000000。
SELECT TO_TIME('13:24:33', '%H:%M:%S');
```

簽名2：使用代表時、分、秒的BIGINT資料，構造以微秒為單位用BIGINT類型表示的時間值。

BIGINT TO_TIME(BIGINT <hour>, BIGINT <minute>, BIGINT <second>)

-- 標準樣本。
-- 返回55800000000。
SELECT TO_TIME(15, 30, 0);

簽名3：將TIMESTAMP類型資料轉換為指定時區的時間值，並返回以微秒為單位用BIGINT類型表示的時間值。

BIGINT TO_TIME(TIMESTAMP <timestamp>[, STRING <time_zone>])

-- 標準樣本。
-- 返回55801123000。
SELECT TO_TIME(TIMESTAMP '2019-09-01 15:30:01.123');

簽名4：將TIMESTAMP_NTZ類型資料轉換為以微秒為單位用BIGINT類型表示的時間值。

BIGINT TO_TIME(TIMESTAMP_NTZ <timestamp_ntz>)

-- 標準樣本。
-- 返回55801123456。
SELECT TO_TIME(TIMESTAMP_NTZ '2025-09-01 15:30:01.123456');

參數說明

參數	描述
value	必填，STRING類型。待轉換的時間值，例如`15:20:23`。
format	必填，STRING類型。待解析value的時間格式。待解析的時間字串value中，每個時間元素都必須有對應的格式元素。例如：15:20對應`hh:mi`、15:20:23對應`hh:mi:ss`。 format目前支援的時間部分的格式元素如下： `hh`、`HH`或`%H`：小時。 `mi`、`MI`或`%M`：分鐘。 `ss`、`SS`或`%S`：秒。 `ff3`：毫秒，單獨匹配秒的小數部分，例如用`%S.ff3`匹配`00.123`。 `%E<number>S`：秒，小數精度為`<number>`位，例如用`%E3S`匹配`00.123`。 `%ES`：有完整6位小數精度的秒，例如`00.123456`。樣本：`hh:mi:ss`、`HH:MI:SS`、`%H:%M:%S`、`%H:%M:%E6S`、`%H:%M:%ES`。
hour	必填，BIGINT類型。待轉換時間的小時。
minute	必填，BIGINT類型。待轉換時間的分鐘。
second	必填，BIGINT類型。待轉換時間的秒。
timestamp	必填，TIMESTAMP類型。待轉換的時間戳記值。
time_zone	可選，STRING類型，用來指定時區，若未指定時區，則預設為當前Session/Project的時區。時區詳情請參見時區列表。說明若未修改過專案時區，則預設為東八區（UTC+08:00）。
timestamp_ntz	必填，TIMESTAMP_NTZ類型。待轉換的無時區時間戳記值。

傳回值說明

返回BIGINT類型。預設以微秒為單位表示時間值，返回規則如下：

當入參為TIMESTAMP或TIMESTAMP_NTZ類型時，去除其日期值和納秒部分，返回結果的時間單位為微秒。
當參數value、timestamp或timestamp_ntz的值為NULL時，返回報錯。
當參數hour、minute或second的值為NULL時，返回NULL。
當參數format格式不合法，或者值為NULL時，返回NULL。

使用樣本

簽名1：TO_TIME(STRING <value>, STRING <format>)。

將時間格式的String類型輸入value，按照指定的format格式解析，並返回以微秒為單位用BIGINT類型表示的時間值。

樣本1：合法format解析時間。

-- 使用標準格式 %H:%M:%S 解析完整時間。
-- 返回48273000000。
SELECT TO_TIME('13:24:33', '%H:%M:%S');

-- 使用 Oracle 風格格式 hh:mi:ss。
-- 返回46860000000。
SELECT TO_TIME('13:01:00', 'hh:mi:ss');

-- 僅包含小時和分鐘。
-- 返回46860000000。
SELECT TO_TIME('13:01', 'hh:mi');

樣本2：含毫秒和微秒的時間字串解析。

-- 包含毫秒部分，使用ff3格式。
-- 返回781000000。
SELECT TO_TIME('13:01', 'mi:ss');

-- ff3表示三位小數秒。
-- 返回781123000。
SELECT TO_TIME('13:01.123', 'mi:ss.ff3');

-- 六位小數秒（微秒），使用%E6S。
-- 返回48273123456。
SELECT TO_TIME('13:24:33.123456', '%H:%M:%E6S');

-- 支援萬用字元%E*S自動識別精度。
-- 返回48273123456。
SELECT TO_TIME('13:24:33.123456', '%H:%M:%E*S');

樣本3：非法或不匹配format處理。

-- format中%h是非法佔位符（應為%H）。
-- 返回NULL。
SELECT TO_TIME('13:24:33', '%h:%m:%s');

樣本4：NULL值輸入處理。

-- format 為 NULL。
-- 返回NULL。
SELECT TO_TIME('13:24:33', NULL);

簽名2：TO_TIME(BIGINT <hour>, BIGINT <minute>, BIGINT <second>)。

使用代表時、分、秒的BIGINT資料，構造以微秒為單位用BIGINT類型表示的時間值。

樣本1：正常傳參構造時間。

-- 使用標準格式 %H:%M:%S 解析完整時間。
-- 返回48273000000。
SELECT TO_TIME('13:24:33', '%H:%M:%S');

-- 使用 Oracle 風格格式 hh:mi:ss。
-- 返回46860000000。
SELECT TO_TIME('13:01:00', 'hh:mi:ss');

-- 僅包含小時和分鐘。
-- 返回46860000000。
SELECT TO_TIME('13:01', 'hh:mi');

樣本2：參數缺失導致失敗。

-- 只傳入兩個參數，不符合函數簽名。
-- 返回NULL。
SELECT TO_TIME(15, 30);

樣本3：NULL值輸入處理。

-- 任意參數為NULL，返回NULL。
-- 返回NULL。
SELECT TO_TIME(15, 30, NULL);

-- 返回NULL。
SELECT TO_TIME(15, NULL, 00);

-- 返回NULL。
SELECT TO_TIME(NULL, 30, 00);

簽名3：TO_TIME(TIMESTAMP <timestamp>[, STRING <time_zone>])。

將TIMESTAMP類型資料轉換為指定時區的時間值，並返回以微秒為單位用BIGINT類型表示的時間值。

樣本1：預設時區下解析 TIMESTAMP。

-- 提取 Shanghai 時間 15:30:01.123 的微秒值。
-- 返回55801123000。
SELECT TO_TIME(TIMESTAMP '2025-09-01 15:30:01.123');

樣本2：配合FORMAT_TIME查看可讀結果。

-- 將 TO_TIME 結果轉為可讀時間字串。
-- 返回15:30:01.123。
SELECT FORMAT_TIME(TO_TIME(TIMESTAMP '2025-09-01 15:30:01.123'), "%H:%M:%S.ff3");

樣本3：指定目標時區。

-- 顯式指定 Asia/Shanghai 時區。
-- 返回55801123000。
SELECT TO_TIME(TIMESTAMP '2025-09-01 15:30:01.123', 'Asia/Shanghai');

樣本4：跨時區轉換。

-- Tokyo 比 Shanghai 快1小時，15:30 在 Tokyo 是 16:30。
-- 返回59401123456。
SELECT TO_TIME(TIMESTAMP '2025-09-01 15:30:01.123456', 'Asia/Tokyo');

-- Bangkok 比 Shanghai 慢1小時，15:30 在 Bangkok 是 14:30。
-- 返回52201123456。
SELECT TO_TIME(TIMESTAMP '2025-09-01 15:30:01.123456789', 'Asia/Bangkok');

簽名4：TO_TIME(TIMESTAMP_NTZ <timestamp_ntz>)。

將TIMESTAMP_NTZ類型資料轉換為以微秒為單位用BIGINT類型表示的時間值。

樣本：直接提取 NTZ 時間。

-- timestamp_ntz 不涉及時區轉換，直接取時間部分。
-- 返回55801123456。
SELECT TO_TIME(TIMESTAMP_NTZ '2025-09-01 15:30:01.123456789');

MaxCompute：TO_TIME