DATETRUNC command format, parameters, and return value - MaxCompute

DATETRUNC, bir tarih veya saat değerini belirtilen zaman birimine göre kırpar ve kırpılmış değeri döndürür.

Kırpma işlemi ayıklama ile aynı değildir. Bir DATETIME değerini çeyreğe göre kırpmak, ilgili çeyreğin ilk gününün zaman damgasını döndürür (örneğin, 2024-10-01 00:00:00 ). Çeyreği EXTRACT kullanarak ayıklamak ise çeyrek numarasını döndürür (örneğin, 4 ).

Syntax

DATETRUNC iki farklı imzayı destekler.

İmza 1 — DATE, DATETIME ve TIMESTAMP_NTZ girişleri için:

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

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

İmza 2 — TIMESTAMP girişleri için, isteğe bağlı saat dilimi dönüştürmesi ile:

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

-- The session time zone is Asia/Shanghai.
-- Returns 2025-01-01 01:00:00.
SELECT DATETRUNC(TIMESTAMP '2025-03-27 16:28:46', 'quarter', 'Asia/Jakarta');

İmza 2, TIMESTAMP değerini belirtilen time_zone değerine dönüştürür, kırpma işlemini uygular ve sonucu oturum veya proje saat diliminde döndürür.

Parameters

date

Zorunludur. Kırpılacak tarih veya zaman damgasıdır. Desteklenen türler: DATE, DATETIME, TIMESTAMP, TIMESTAMP_NTZ.

MaxCompute projeniz V1.0 veri türü sürümünü kullanıyorsa, DATETIME biçimiyle eşleşen yyyy-mm-dd hh:mi:ss formatındaki bir STRING değeri de kabul edilir. İşlev, kırpma işleminden önce bu değeri örtük olarak DATETIME türüne dönüştürür.

date_part

Zorunludur. Kırpılacak zaman birimidir. Bir STRING sabiti olmalıdır.

Zaman birimi	Değer	Kırpma davranışı
Yıl	`year` veya `yyyy`	Yılın ilk gününü döndürür; saat kısmı `00:00:00` olarak ayarlanır.
Çeyrek	`quarter` veya `q`	Çeyreğin ilk gününü döndürür; saat kısmı `00:00:00` olarak ayarlanır.
Ay	`month`, `mon` veya `mm`	Ayın ilk gününü döndürür; saat kısmı `00:00:00` olarak ayarlanır.
Hafta	`week` veya `week(monday)`	Haftanın Pazartesi gününü döndürür; saat kısmı `00:00:00` olarak ayarlanır.
Hafta (özel başlangıç)	`week(weekday)`	Haftanın belirtilen gününü döndürür; saat kısmı `00:00:00` olarak ayarlanır. Geçerli değerler: `SUNDAY`, `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`, `SATURDAY`
ISO haftası	`isoweek`	ISO 8601 haftasının Pazartesi gününü döndürür; saat kısmı `00:00:00` olarak ayarlanır.
Gün	`day` veya `dd`	Tarihi korur; saat kısmı `00:00:00` olarak ayarlanır.
Saat	`hour` veya `hh`	Saat düzeyine kadar korur; dakika ve saniye kısımları `00:00` olarak ayarlanır.
Dakika	`mi`	Dakika düzeyine kadar korur; saniye kısmı `00` olarak ayarlanır.
Saniye	`ss`	Saniye düzeyine kadar korur; saniyenin ondalık kısımları kaldırılır.
Milisaniye	`ff3`	Milisaniye hassasiyetine kadar korur.

time_zone

İsteğe bağlıdır. Yalnızca İmza 2 için geçerlidir. TIMESTAMP değerinin kırpılmadan önce dönüştürüleceği saat dilimini belirten bir STRING değeridir. Belirtilmezse oturum veya proje saat dilimi kullanılır.

Proje saat dilimi değiştirilmediyse varsayılan değer Çin Standart Saati'dir (UTC+08:00).

Return value

date parametresiyle aynı veri türünü döndürür. Aşağıdaki özel durumlar geçerlidir:

Koşul	Sonuç
`date` değeri DATE, DATETIME, TIMESTAMP veya TIMESTAMP_NTZ türünde değilse	Hata
`date` değeri NULL ise	Hata
`date_part` değeri NULL ise	NULL
`date_part` değeri sabit değilse, desteklenmeyen bir biçimdeyse veya STRING türünde değilse	Hata

Examples

Basic examples

Aşağıdaki örneklerde DATE, DATETIME ve TIMESTAMP_NTZ girişleri için İmza 1 kullanılmıştır.

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

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

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

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

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

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

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

Farklı date_part değerlerinin aynı giriş üzerinde nasıl bir etki yarattığını görmek için sorguları yan yana çalıştırın:

SELECT
  DATETRUNC(DATETIME'2024-12-07 16:28:46', 'yyyy')    AS truncated_to_year,
  DATETRUNC(DATETIME'2024-12-07 16:28:46', 'quarter')  AS truncated_to_quarter,
  DATETRUNC(DATETIME'2024-12-07 16:28:46', 'month')    AS truncated_to_month,
  DATETRUNC(DATETIME'2024-12-07 16:28:46', 'week')     AS truncated_to_week,
  DATETRUNC(DATETIME'2024-12-07 16:28:46', 'day')      AS truncated_to_day,
  DATETRUNC(DATETIME'2024-12-07 16:28:46', 'hour')     AS truncated_to_hour;

Çıktı:

truncated_to_year	truncated_to_quarter	truncated_to_month	truncated_to_week	truncated_to_day	truncated_to_hour
2024-01-01 00:00:00	2024-10-01 00:00:00	2024-12-01 00:00:00	2024-12-02 00:00:00	2024-12-07 00:00:00	2024-12-07 16:00:00

Examples with time_zone

date parametresi bir TIMESTAMP olduğunda, kırpma işleminin uygulanacağı saat dilimini belirtmek için time_zone parametresini kullanın. Sonuç, oturum veya proje saat diliminde döndürülür.

-- Set the session time zone to Asia/Shanghai.
SET odps.sql.timezone=Asia/Shanghai;

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

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

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

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

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

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

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

STRING input (V1.0 data type edition)

V1.0 veri türü sürümü etkinleştirildiğinde, yyyy-mm-dd hh:mi:ss biçimiyle eşleşen bir STRING değeri örtük olarak DATETIME türüne dönüştürülür. Ondalık saniye içeren dizeler bu biçimle eşleşmez ve NULL döndürür.

-- Set the data type edition to V1.0.
SET odps.sql.type.system.odps2=false;
SET odps.sql.hive.compatible=false;

-- Returns NULL. The string includes milliseconds, which do not match the DATETIME format.
SELECT DATETRUNC('2025-07-27 16:28:46.123', 'mi');

-- Returns 2025-07-27 16:28:00. The string matches the DATETIME format.
SELECT DATETRUNC('2025-07-27 16:28:46', 'mi');

Related functions

DATETRUNC bir tarih işlevidir. Tarih hesaplama ve dönüştürme işlevleri için bkz. Tarih işlevleri.