FROM_UTC_TIMESTAMP command format, parameters, and return value - MaxCompute: Central de Documentação do Alibaba Cloud

Converte um timestamp UTC para um fuso horário especificado e retorna um valor TIMESTAMP.

Importante

Sempre que possível, use TO_TIMESTAMP_NTZ em vez de FROM_UTC_TIMESTAMP. A função FROM_UTC_TIMESTAMP aplica um deslocamento de fuso horário da sessão ou do projeto quando a entrada é BIGINT, o que pode gerar resultados inesperados.

Sintaxe

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

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`timestamp`	BIGINT, STRING, DATETIME, TIMESTAMP ou TIMESTAMP_NTZ	Sim	Timestamp UTC a converter. Consulte as regras de tipo de entrada abaixo.
`time_zone`	STRING	Sim	Fuso horário de destino. Exemplos: `Asia/Shanghai`, `Etc/GMT` ou `PST`.

Regras de tipo de entrada para timestamp:

BIGINT: interpretado como milissegundos. A função adiciona o valor à época 1970-01-01 00:00:00 UTC e aplica o deslocamento de fuso horário atual da sessão ou do projeto para determinar o timestamp de entrada. A configuração de fuso horário da sessão ou do projeto afeta a saída.
STRING: deve estar no formato yyyy-mm-dd ou yyyy-mm-dd hh:mi:ss. Valores em outros formatos retornam NULL.
DATETIME, TIMESTAMP, TIMESTAMP_NTZ: conversão direta de UTC para o fuso horário de destino. A configuração de fuso horário da sessão ou do projeto não afeta a entrada nem a saída.

Valor de retorno

Retorna um valor TIMESTAMP no fuso horário especificado.

Condição	Resultado
`timestamp` não é BIGINT, STRING, DATETIME, TIMESTAMP ou TIMESTAMP_NTZ	Erro
`timestamp` é uma STRING fora do formato exigido	NULL
`timestamp` é NULL	Erro
`time_zone` é NULL	NULL

Observações de uso

O fuso horário da sessão afeta apenas entradas BIGINT. Se timestamp for BIGINT, o resultado varia conforme a configuração odps.sql.timezone. Para os demais tipos de entrada, o fuso horário da sessão ou do projeto não exerce efeito.
Resultados via instance tunnel podem divergir. Ao executar esta função com um cliente MaxCompute e use_instance_tunnel definido como true, o resultado exibido no odpscmd pode diferir daquele apresentado no logview. O resultado do logview é a fonte autoritativa.

Exemplos

Entrada BIGINT: fuso horário da sessão é Asia/Shanghai

A entrada corresponde a 0 milissegundos (tempo de época). A função soma 0 ms a 1970-01-01 00:00:00 UTC e aplica o deslocamento de Asia/Shanghai (+8 horas), obtendo o timestamp de entrada 1970-01-01 08:00:00. A conversão desse valor para Asia/Shanghai retorna 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;

Resultado:

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

Entrada BIGINT: fuso horário da sessão é Etc/GMT

Mesma consulta com odps.sql.timezone definido como Etc/GMT. Como o deslocamento da sessão muda, os resultados são diferentes.

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;

Resultado:

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

Entrada não BIGINT: fuso horário da sessão não tem efeito

Para entradas STRING, DATETIME, TIMESTAMP e TIMESTAMP_NTZ, a função converte o valor diretamente de UTC para o fuso horário de destino. A configuração odps.sql.timezone é irrelevante.

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

Funções relacionadas

FROM_UTC_TIMESTAMP é uma função de data. Para outras funções de cálculo e conversão de datas, consulte Funções de data.