FROM_UTC_TIMESTAMP command format, parameters, and return value - MaxCompute

Convertit un horodatage UTC vers un fuseau horaire spécifié et renvoie une valeur TIMESTAMP.

Important

Utilisez TO_TIMESTAMP_NTZ plutôt que FROM_UTC_TIMESTAMP dans la mesure du possible. FROM_UTC_TIMESTAMP applique le décalage du fuseau horaire de la session ou du projet lorsque l'entrée est de type BIGINT, ce qui peut produire des résultats inattendus.

Syntaxe

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

Paramètres

Paramètre	Type	Obligatoire	Description
`timestamp`	BIGINT, STRING, DATETIME, TIMESTAMP ou TIMESTAMP_NTZ	Oui	L'horodatage UTC à convertir. Consultez les règles relatives aux types d'entrée ci-dessous.
`time_zone`	STRING	Oui	Le fuseau horaire cible. Par exemple : `Asia/Shanghai`, `Etc/GMT` ou `PST`.

Règles relatives aux types d'entrée pour timestamp :

BIGINT — Traité comme des millisecondes. La fonction ajoute la valeur à l'époque 1970-01-01 00:00:00 UTC, puis applique le décalage du fuseau horaire actuel de la session ou du projet pour déterminer l'horodatage d'entrée. Le résultat est affecté par le paramètre de fuseau horaire de la session ou du projet.
STRING — Doit être au format yyyy-mm-dd ou yyyy-mm-dd hh:mi:ss. Les valeurs dans d'autres formats renvoient NULL.
DATETIME, TIMESTAMP, TIMESTAMP_NTZ — Convertis directement de l'UTC vers le fuseau horaire cible. Le paramètre de fuseau horaire de la session ou du projet n'affecte ni l'entrée ni le résultat.

Valeur de retour

Renvoie une valeur TIMESTAMP dans le fuseau horaire spécifié.

Condition	Résultat
`timestamp` n'est pas de type BIGINT, STRING, DATETIME, TIMESTAMP ou TIMESTAMP_NTZ	Erreur
`timestamp` est une chaîne STRING ne correspondant pas au format requis	NULL
`timestamp` est NULL	Erreur
`time_zone` est NULL	NULL

Remarques sur l'utilisation

Le fuseau horaire de la session n'affecte que les entrées de type BIGINT. Lorsque timestamp est de type BIGINT, le résultat varie selon le paramètre odps.sql.timezone. Pour tous les autres types d'entrée, le fuseau horaire de la session ou du projet n'a aucun effet.
Les résultats via Instance Tunnel peuvent différer. Si vous exécutez cette fonction via un client MaxCompute avec use_instance_tunnel défini sur true, le résultat affiché dans odpscmd peut différer de celui présent dans logview. Le résultat de logview fait autorité.

Exemples

Entrée BIGINT : le fuseau horaire de la session est Asia/Shanghai

L'entrée est 0 milliseconde (temps d'époque). La fonction ajoute 0 ms à 1970-01-01 00:00:00 UTC, puis applique le décalage Asia/Shanghai (+8 heures) pour obtenir l'horodatage d'entrée 1970-01-01 08:00:00. La conversion vers Asia/Shanghai renvoie 1970-01-01 16:00:00.

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;

Résultat :

+---------------------+---------------------+---------------------+
| timestamp1          | timestamp2          | timestamp3          |
+---------------------+---------------------+---------------------+
| 1970-01-01 16:00:00 | 1970-01-01 08:20:30 | 1970-01-01 07:39:30 |
+---------------------+---------------------+---------------------+

Entrée BIGINT : le fuseau horaire de la session est Etc/GMT

Même requête avec odps.sql.timezone défini sur Etc/GMT. Le décalage de la session change, donc les résultats diffèrent.

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;

Résultat :

+---------------------+---------------------+---------------------+
| timestamp1          | timestamp2          | timestamp3          |
+---------------------+---------------------+---------------------+
| 1970-01-01 08:00:00 | 1970-01-01 00:20:30 | 1969-12-31 23:39:30 |
+---------------------+---------------------+---------------------+

Entrée non-BIGINT : le fuseau horaire de la session n'a aucun effet

Pour les entrées de type STRING, DATETIME, TIMESTAMP et TIMESTAMP_NTZ, la fonction convertit directement la valeur de l'UTC vers le fuseau horaire cible. Le paramètre odps.sql.timezone n'est pas pertinent.

-- Session time zone is Asia/Shanghai, but it does not affect the output.
SET odps.sql.timezone = Asia/Shanghai;

-- STRING (yyyy-mm-dd): returns 2025-08-31 09:00:00
SELECT FROM_UTC_TIMESTAMP('2025-08-31', 'Asia/Seoul');

-- STRING (yyyy-mm-dd hh:mi:ss): returns 2025-03-05 23:30:15
SELECT FROM_UTC_TIMESTAMP('2025-03-05 15:30:15', 'Asia/Shanghai');

-- STRING with sub-second precision: returns 2025-03-05 08:00:00.123456789
SELECT FROM_UTC_TIMESTAMP('2025-03-05 00:00:00.123456789', 'Asia/Shanghai');

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

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

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

Fonctions associées

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