Format, parameter, dan nilai kembali perintah FROM_UTC_TIMESTAMP - MaxCompute

Fungsi FROM_UTC_TIMESTAMP mengonversi timestamp dari Coordinated Universal Time (UTC) ke zona waktu yang ditentukan.

Catatan penggunaan

Untuk memastikan penanganan zona waktu yang jelas dan konsisten, gunakan fungsi TO_TIMESTAMP_NTZ. Hal ini membantu menghindari hasil yang tidak terduga akibat cara fungsi FROM_UTC_TIMESTAMP memproses zona waktu.

Sintaksis

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

Parameter

timestamp: Wajib. Timestamp yang akan dikonversi. Parameter ini mendukung tipe data BIGINT, STRING, DATETIME, TIMESTAMP, dan TIMESTAMP_NTZ.
- Jika input berupa STRING, formatnya harus yyyy-mm-dd atau yyyy-mm-dd hh:mi:ss.
- Jika input berupa nilai BIGINT dalam milidetik, fungsi ini menambahkan nilai tersebut ke epoch time 1970-01-01 00:00:00 UTC, lalu menerapkan offset berdasarkan zona waktu sesi atau proyek saat ini untuk menentukan timestamp input.
time_zone: Wajib. STRING yang menentukan zona waktu tujuan.

Nilai kembali

Mengembalikan nilai TIMESTAMP dalam zona waktu yang ditentukan. Aturan berikut berlaku:

Jika timestamp bukan bertipe BIGINT, STRING, DATETIME, TIMESTAMP, atau TIMESTAMP_NTZ, maka error dikembalikan.
Jika timestamp berupa nilai STRING yang tidak sesuai dengan format yang dipersyaratkan, maka NULL dikembalikan.
Jika timestamp bernilai NULL, maka error dikembalikan.
Jika time_zone bernilai NULL, maka NULL dikembalikan.

Contoh

Contoh 1: Jika parameter input berupa BIGINT, fungsi ini menambahkan nilai milidetik ke epoch time 1970-01-01 00:00:00 UTC, lalu menerapkan offset berdasarkan zona waktu sesi atau proyek saat ini untuk menentukan timestamp input.

-- Setel zona waktu sesi/proyek ke 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;
-- Hasil berikut dikembalikan:
+---------------------+---------------------+---------------------+
| timestamp1          | timestamp2          | timestamp3          |
+---------------------+---------------------+---------------------+
| 1970-01-01 16:00:00 | 1970-01-01 08:20:30 | 1970-01-01 07:39:30 |
+---------------------+---------------------+---------------------+


-- Setel zona waktu sesi/proyek ke 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;
-- Hasil berikut dikembalikan:
+---------------------+---------------------+---------------------+
| timestamp1          | timestamp2          | timestamp3          |
+---------------------+---------------------+---------------------+
| 1970-01-01 08:00:00 | 1970-01-01 00:20:30 | 1969-12-31 23:39:30 |
+---------------------+---------------------+---------------------+

Contoh 2: Jika parameter input berupa tipe lain yang didukung, fungsi ini mengonversi timestamp dari UTC ke zona waktu yang ditentukan. Dalam kasus ini, timestamp input dan output tidak dipengaruhi oleh zona waktu sesi atau proyek.

-- Pengaturan zona waktu sesi/proyek tidak memengaruhi timestamp input maupun output.
SET odps.sql.timezone = Asia/Shanghai;

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

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

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

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

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

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

Catatan

Jika Anda menjalankan fungsi ini pada client MaxCompute dengan `use_instance_tunnel` diatur ke `true`, hasil yang ditampilkan di `odpscmd` dan `logview` mungkin tidak konsisten. Hasil di `logview` yang berlaku.

Fungsi terkait

FROM_UTC_TIMESTAMP adalah fungsi tanggal. Untuk informasi selengkapnya tentang fungsi yang terkait dengan perhitungan dan konversi tanggal, lihat Fungsi tanggal.