Format, parameter, dan nilai kembali perintah DATETRUNC - MaxCompute

Fungsi DATETRUNC memotong nilai tanggal atau waktu ke satuan waktu tertentu date_part dan mengembalikan nilai yang telah dipotong tersebut.

Sintaks

Fungsi ini mendukung dua tanda tangan berikut.

Signature 1: Memotong nilai DATE, DATETIME, atau TIMESTAMP_NTZ ke satuan waktu yang ditentukan oleh date_part dan mengembalikan nilai yang telah dipotong.

DATE|DATETIME|TIMESTAMP_NTZ DATETRUNC(DATE|DATETIME|TIMESTAMP_NTZ <date>, STRING <date_part>)

-- Contoh standar.
-- Mengembalikan 2025-01-01 00:00:00.
SELECT DATETRUNC(DATETIME '2025-12-07 16:28:46', 'yyyy');

Signature 2: Mengonversi nilai TIMESTAMP ke zona waktu tertentu, memotongnya ke satuan waktu yang ditentukan oleh date_part, lalu mengembalikan nilai waktu dalam zona waktu sesi atau proyek saat ini.

TIMESTAMP DATETRUNC(TIMESTAMP <date>,STRING <date_part>[, STRING <time_zone>])

-- Contoh standar.
-- Zona waktu session atau proyek saat ini adalah Asia/Shanghai.
-- Mengembalikan 2025-01-01 01:00:00.
SELECT DATETRUNC(TIMESTAMP '2025-03-27 16:28:46', 'quarter', 'Asia/Jakarta');

Parameter

date: Diperlukan. Sebuah tanggal atau timestamp. Tipe data yang didukung adalah DATE, DATETIME, TIMESTAMP, dan TIMESTAMP_NTZ.
Jika proyek MaxCompute Anda menggunakan edisi tipe data V1.0, parameter input dapat berupa STRING. String tersebut harus sesuai dengan format DATETIME, yaitu yyyy-mm-dd hh:mi:ss, seperti 2025-07-21 00:00:00. Fungsi ini secara implisit mengonversi string tersebut ke tipe DATETIME untuk perhitungan.

date_part: Wajib. Satuan waktu untuk pemotongan. Parameter ini harus berupa konstanta STRING. Nilai-nilai berikut didukung:

Unit waktu	Nilai
Tahun	`year` atau `yyyy`
Kuartal	`quarter` atau `q`
Bulan	`month`, `mon`, atau `mm`
Minggu	`week`: Minggu dimulai pada hari Senin. Ini setara dengan `week(monday)`. `week(weekday)`: Minggu dimulai pada hari yang ditentukan `(weekday)`. Nilai yang valid: SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, dan SATURDAY.
Minggu ISO	`isoweek` menggunakan batas minggu yang didefinisikan dalam ISO 8601. Minggu ISO dimulai pada hari Senin.
Hari	`day` atau `dd`
Jam	`hour` atau `hh`
Menit	`mi`
Kedua,	`ss`
Milidetik	`ff3`

time_zone: Opsional. STRING yang menentukan zona waktu. Jika tidak ditentukan, zona waktu sesi atau proyek saat ini digunakan sebagai default.
Catatan
Jika Anda belum mengubah zona waktu proyek, defaultnya adalah Waktu Standar China (UTC+08:00).

Nilai kembali

Fungsi ini mengembalikan nilai dengan tipe data yang sama dengan parameter input date. Tipe data yang didukung adalah DATE, DATETIME, TIMESTAMP, dan TIMESTAMP_NTZ. Aturan berikut berlaku:

Jika date bukan tipe DATE, DATETIME, TIMESTAMP, atau TIMESTAMP_NTZ, kesalahan akan dikembalikan.
Jika nilai date adalah NULL, fungsi akan mengembalikan error.
Jika nilai date_part adalah NULL, fungsi akan mengembalikan NULL.
Jika date_part berupa nilai non-konstanta, format yang tidak didukung, atau tipe data lain, fungsi akan mengembalikan error.

Contoh

Contoh 1: Contoh dasar

-- Mengembalikan 2024-01-01 00:00:00.
SELECT DATETRUNC(DATETIME'2024-12-07 16:28:46', 'yyyy');

-- Mengembalikan 2024-12-01 00:00:00.
SELECT DATETRUNC(DATETIME'2024-12-07 16:28:46', 'MONTH');

-- Mengembalikan 2024-12-02.
SELECT DATETRUNC(DATE'2024-12-07', 'week(monday)');

-- Mengembalikan 2024-10-01 00:00:00.
SELECT DATETRUNC(TIMESTAMP_NTZ'2024-12-07 16:28:46', 'q');

-- Mengembalikan 2024-12-07 16:28:46.
SELECT DATETRUNC(TIMESTAMP_NTZ'2024-12-07 16:28:46.123', 'ss');

-- Mengembalikan 2024-12-07 16:28:46.123. 
SELECT DATETRUNC(TIMESTAMP_NTZ'2024-12-07 16:28:46.123456', 'ff3');

-- Mengembalikan NULL.
SELECT DATETRUNC(DATE'2024-12-07', NULL);

Contoh 2: Gunakan parameter time_zone untuk menentukan zona waktu

Jika parameter date bertipe TIMESTAMP, Anda dapat menggunakan parameter time_zone untuk menentukan zona waktu. Fungsi ini mengembalikan nilai waktu dalam zona waktu sesi atau proyek saat ini.

-- Atur zona waktu session ke Asia/Shanghai.
SET odps.sql.timezone=Asia/Shanghai;
-- Mengembalikan 2024-01-01 00:00:00.
SELECT DATETRUNC(TIMESTAMP '2024-12-07 16:28:46', 'yyyy');

-- Mengembalikan 2025-01-01 01:00:00.
SELECT DATETRUNC(TIMESTAMP '2025-03-27 16:28:46', 'quarter','Asia/Jakarta');

-- Mengembalikan 2025-03-21 01:00:00.
SELECT DATETRUNC(TIMESTAMP '2025-03-27 16:28:46', 'week(friday)','Asia/Jakarta');

-- Mengembalikan 2025-03-24 08:00:00.
SELECT DATETRUNC(TIMESTAMP '2025-03-27 16:28:46', 'isoweek','Etc/GMT');

-- Mengembalikan 2025-11-07 01:00:00.
SELECT DATETRUNC(TIMESTAMP '2025-11-07 10:30:00','dd','Asia/Jakarta');

-- Mengembalikan 2025-11-07 10:00:00.
SELECT DATETRUNC(TIMESTAMP '2025-11-07 10:30:00','hour','Asia/Jakarta');

-- Mengembalikan 2025-11-07 10:30:00.
SELECT DATETRUNC(TIMESTAMP '2025-11-07 10:30:00','mi','Asia/Jakarta');

Contoh 3: Parameter date bertipe STRING

Jika proyek MaxCompute Anda menggunakan edisi tipe data V1.0, dan parameter date berupa STRING yang sesuai dengan format DATETIME yyyy-mm-dd hh:mi:ss, string tersebut secara implisit dikonversi ke tipe DATETIME untuk perhitungan.

-- Atur edisi tipe data ke V1.0.
SET odps.sql.type.system.odps2=false;
SET odps.sql.hive.compatible=false;

-- Contoh salah: Parameter input berikut berupa STRING tetapi tidak sesuai dengan format DATETIME. Fungsi mengembalikan NULL.
-- Mengembalikan NULL.
SELECT DATETRUNC('2025-07-27 16:28:46.123','mi');

-- Contoh benar: Parameter input berikut berupa STRING yang sesuai dengan format DATETIME.
-- Mengembalikan 2025-07-27 16:28:00.
SELECT DATETRUNC('2025-07-27 16:28:46', 'mi');

Fungsi terkait

DATETRUNC adalah fungsi tanggal. Untuk informasi lebih lanjut tentang fungsi untuk perhitungan dan konversi tanggal, lihat Fungsi tanggal.