FROM_UTC_TIMESTAMP命令格式、參數和傳回值 - MaxCompute

FROM_UTC_TIMESTAMP函數用於將一個UTC時區的時間戳記轉換成一個指定時區的時間戳記，即將一個UTC時區的時間戳記按照指定的時區顯示。

注意事項

為確保時區處理的清晰性與一致性，推薦使用TO_TIMESTAMP_NTZ函數。避免由於FROM_UTC_TIMESTAMP函數在處理時區時導致的返回結果不符合預期。

命令格式

TIMESTAMP FROM_UTC_TIMESTAMP (BIGINT|STRING|DATETIME|TIMESTAMP|TIMESTAMP_NTZ <timestamp>, STRING <time_zone>)

參數說明

timestamp：必填。待轉換的時間戳記。支援BIGINT、STRING、DATETIME、TIMESTAMP或TIMESTAMP_NTZ類型。
- 如果輸入為STRING類型，日期格式需包含yyyy-mm-dd或yyyy-mm-dd hh:mi:ss。
- 如果輸入為BIGINT類型的毫秒值，系統會以 1970-01-01 00:00:00 UTC 為起點加上毫秒值，再根據當前Session/Project時區設定進行時區位移，作為輸入時間戳記。
time_zone：必填。用於指定需要轉換的目標時區。STRING類型。

傳回值說明

返回TIMESTAMP類型指定時區的時間戳記。返回規則如下：

timestamp非BIGINT、STRING、DATETIME、TIMESTAMP或TIMESTAMP_NTZ類型，返回報錯。
timestamp為不符合格式要求的STRING類型，返回NULL。
timestamp為NULL，返回報錯。
time_zone為NULL，返回NULL。

使用樣本

樣本1：當輸入參數為BIGINT時，系統會以 1970-01-01 00:00:00 UTC 為起點加上毫秒值，再根據當前Session/Project時區設定進行時區位移，作為輸入時間戳記。

-- 設定Session/Project時區為Asia/Shanghai時
SET odps.sql.timezone = Asia/Shanghai;
SELECT  FROM_UTC_TIMESTAMP(0, 'Asia/Shanghai') AS TIMESTAMP1
        ,FROM_UTC_TIMESTAMP(1230000,'Etc/GMT') AS TIMESTAMP2
        ,FROM_UTC_TIMESTAMP(-1230000,'Etc/GMT') AS TIMESTAMP3;
-- 返回：
+---------------------+---------------------+---------------------+
| timestamp1          | timestamp2          | timestamp3          |
+---------------------+---------------------+---------------------+
| 1970-01-01 16:00:00 | 1970-01-01 08:20:30 | 1970-01-01 07:39:30 |
+---------------------+---------------------+---------------------+


-- 設定Session/Project時區為Etc/GMT
SET odps.sql.timezone = Etc/GMT;
SELECT  FROM_UTC_TIMESTAMP(0, 'Asia/Shanghai') AS TIMESTAMP1
        ,FROM_UTC_TIMESTAMP(1230000,'Etc/GMT') AS TIMESTAMP2
        ,FROM_UTC_TIMESTAMP(-1230000,'Etc/GMT') AS TIMESTAMP3;
-- 返回：
+---------------------+---------------------+---------------------+
| timestamp1          | timestamp2          | timestamp3          |
+---------------------+---------------------+---------------------+
| 1970-01-01 08:00:00 | 1970-01-01 00:20:30 | 1969-12-31 23:39:30 |
+---------------------+---------------------+---------------------+

樣本2：當輸入參數為其他類型時，函數將時間戳記從UTC時區轉換為指定時區時間戳記並返回，此時輸出與輸出時間戳記均與Session/Project時區設定無關。

-- 設定Session/Project時區值，對輸入與輸出時間戳記無影響
SET odps.sql.timezone = Asia/Shanghai;

-- 返回 2025-08-31 09:00:00
SELECT FROM_UTC_TIMESTAMP('2025-08-31', 'Asia/Seoul');

-- 返回 2025-03-05 23:30:15
SELECT FROM_UTC_TIMESTAMP('2025-03-05 15:30:15','Asia/Shanghai');

-- 返回 2025-03-05 08:00:00.123456789
SELECT FROM_UTC_TIMESTAMP('2025-03-05 00:00:00.123456789','Asia/Shanghai');

-- 返回 2025-03-04 16:00:00
SELECT FROM_UTC_TIMESTAMP(DATETIME '2025-03-05 00:00:00','PST');

-- 返回 2025-03-06 00:30:15.123
SELECT FROM_UTC_TIMESTAMP(TIMESTAMP '2025-03-05 15:30:15.123','Asia/Seoul');

-- 返回 2025-03-05 23:30:15.123
SELECT FROM_UTC_TIMESTAMP(TIMESTAMP_NTZ '2025-03-05 15:30:15.123','Asia/Shanghai');

說明

若使用MaxCompute用戶端執行，當use_instance_tunnel為true時，可能出現 odpscmd與logview的兩邊返回結果的屏顯不一致的情況，結果請以logview裡的result為準。

MaxCompute：FROM_UTC_TIMESTAMP

注意事項

命令格式

參數說明

傳回值說明

使用樣本

相關函數