FROM_UTC_TIMESTAMP command format, parameters, and return value - MaxCompute

FROM_UTC_TIMESTAMP 関数は、協定世界時 (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 に加算します。その後、現在のセッションまたはプロジェクトのタイムゾーンに基づいてオフセットが適用され、入力タイムスタンプが決定されます。
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 に加算します。その後、現在のセッションまたはプロジェクトのタイムゾーンに基づいてオフセットが適用され、入力タイムスタンプが決定されます。

-- セッション/プロジェクトのタイムゾーンを 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 |
+---------------------+---------------------+---------------------+


-- セッション/プロジェクトのタイムゾーンを 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 のタイムスタンプを指定されたタイムゾーンに変換します。この場合、入力と出力のタイムスタンプは、セッションまたはプロジェクトのタイムゾーンの影響を受けません。

-- セッション/プロジェクトのタイムゾーン設定は、入力または出力のタイムスタンプに影響しません。
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');

説明

`use_instance_tunnel` を `true` に設定した MaxCompute クライアントでこの関数を実行すると、`odpscmd` と `logview` に表示される結果が一致しない場合があります。`logview` の結果が優先されます。

MaxCompute:FROM_UTC_TIMESTAMP

注意事項

構文

パラメーター

戻り値

例

関連関数