DATETRUNC command format, parameters, and return value - MaxCompute

La fonction DATETRUNC tronque une valeur de date ou d'heure à l'unité de temps spécifiée et renvoie la valeur tronquée.

La troncature diffère de l'extraction. Tronquer un DATETIME au trimestre renvoie l'horodatage du premier jour de ce trimestre (par exemple, 2024-10-01 00:00:00 ). En revanche, extraire le trimestre avec la fonction EXTRACT renvoie le numéro du trimestre (par exemple, 4 ).

Syntaxe

DATETRUNC accepte deux signatures.

Signature 1 — pour les entrées DATE, DATETIME et TIMESTAMP_NTZ :

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');

Signature 2 — pour les entrées TIMESTAMP, avec conversion facultative du fuseau horaire :

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');

La signature 2 convertit le TIMESTAMP dans le time_zone spécifié, le tronque, puis renvoie le résultat dans le fuseau horaire de la session ou du projet.

Paramètres

date

Obligatoire. Date ou horodatage à tronquer. Types pris en charge : DATE, DATETIME, TIMESTAMP, TIMESTAMP_NTZ.

Si votre projet MaxCompute utilise l'édition des types de données V1.0, une chaîne correspondant au format DATETIME yyyy-mm-dd hh:mi:ss est également acceptée. La fonction la convertit implicitement en DATETIME avant de la tronquer.

date_part

Obligatoire. Unité de temps cible de la troncature. Doit être une constante de type STRING.

|
**Unité de temps**
|
**Valeur**
|
**Comportement de troncature**
| | --- | --- | --- | |
Année
|
`year` ou `yyyy`
|
Renvoie le premier jour de l'année ; l'heure est définie sur `00:00:00`
| |
Trimestre
|
`quarter` ou `q`
|
Renvoie le premier jour du trimestre ; l'heure est définie sur `00:00:00`
| |
Mois
|
`month`, `mon` ou `mm`
|
Renvoie le premier jour du mois ; l'heure est définie sur `00:00:00`
| |
Semaine
|
`week` ou `week(monday)`
|
Renvoie le lundi de la semaine ; l'heure est définie sur `00:00:00`
| |
Semaine (début personnalisé)
|
`week(weekday)`
|
Renvoie le jour spécifié de la semaine ; l'heure est définie sur `00:00:00`. Valeurs valides : `SUNDAY`, `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`, `SATURDAY`
| |
Semaine ISO
|
`isoweek`
|
Renvoie le lundi de la semaine ISO 8601 ; l'heure est définie sur `00:00:00`
| |
Jour
|
`day` ou `dd`
|
Conserve la date ; l'heure est définie sur `00:00:00`
| |
Heure
|
`hour` ou `hh`
|
Conserve l'heure ; les minutes et les secondes sont définies sur `00:00`
| |
Minute
|
`mi`
|
Conserve la minute ; les secondes sont définies sur `00`
| |
Seconde
|
`ss`
|
Conserve la seconde ; les fractions de seconde sont supprimées
| |
Milliseconde
|
`ff3`
|
Conserve la précision milliseconde
|

time_zone

Facultatif. Uniquement pour la signature 2. Chaîne indiquant le fuseau horaire dans lequel convertir le TIMESTAMP avant la troncature. Si ce paramètre est omis, le fuseau horaire de la session ou du projet est utilisé.

Si le fuseau horaire du projet n'a pas été modifié, la valeur par défaut est l'heure normale de Chine (UTC+08:00).

Valeur de retour

Renvoie le même type de données que date. Les cas limites suivants s'appliquent :

|
**Condition**
|
**Résultat**
| | --- | --- | |
`date` n'est ni de type DATE, ni DATETIME, ni TIMESTAMP, ni TIMESTAMP_NTZ
|
Erreur
| |
`date` est NULL
|
Erreur
| |
`date_part` est NULL
|
NULL
| |
`date_part` n'est pas une constante, possède un format non pris en charge ou n'est pas de type STRING
|
Erreur
|

Exemples

Exemples de base

Les exemples suivants utilisent la signature 1 avec des entrées DATE, DATETIME et TIMESTAMP_NTZ.

-- 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);

Pour observer l'impact des différentes valeurs de date_part sur une même entrée, exécutez-les côte à côte :

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;

Sortie :

|
**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
|

Exemples avec time_zone

Lorsque date est un TIMESTAMP, utilisez time_zone pour indiquer le fuseau horaire dans lequel appliquer la troncature. Le résultat est renvoyé dans le fuseau horaire de la session ou du projet.

-- 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');

Entrée STRING (édition des types de données V1.0)

Lorsque l'édition des types de données V1.0 est active, une chaîne correspondant à yyyy-mm-dd hh:mi:ss est implicitement convertie en DATETIME. Les chaînes contenant des fractions de seconde ne correspondent pas au format attendu et renvoient NULL.

-- 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');

Fonctions associées

DATETRUNC est une fonction de date. Pour les fonctions de calcul et de conversion de dates, consultez la Présentation des fonctions de date et d'heure.