Categorias:: Funções de data e hora

CONVERT_TIMEZONE¶

Converte um carimbo de data/hora em outro fuso horário.

Sintaxe¶

CONVERT_TIMEZONE( <source_tz> , <target_tz> , <source_timestamp_ntz> )

CONVERT_TIMEZONE( <target_tz> , <source_timestamp> )

Argumentos¶

source_tz: Cadeia de caracteres especificando o fuso horário para o carimbo de data/hora de entrada. Necessário para carimbos de data/hora sem fuso horário (ou seja, TIMESTAMP_NTZ).
target_tz: Cadeia de caracteres especificando o fuso horário para o qual o carimbo de data/hora de entrada é convertido.
source_timestamp_ntz: Para a versão de 3 argumentos, a cadeia de caracteres especificando o carimbo de data/hora a converter (deve ser TIMESTAMP_NTZ).
source_timestamp: Para a versão de 2 argumentos, a cadeia de caracteres especificando o carimbo de data/hora a converter (pode ser qualquer variante de carimbo de data/hora, incluindo TIMESTAMP_NTZ).

Retornos¶

Retorna um valor do tipo TIMESTAMP_NTZ, TIMESTAMP_TZ ou NULL:

Para a versão de 3 argumentos, retorna um valor do tipo TIMESTAMP_NTZ.
Para a versão de 2 argumentos, retorna um valor do tipo TIMESTAMP_TZ.
Se algum argumento for NULL, retorna NULL.

Notas de uso¶

O formato de exibição dos carimbos de data/hora na saída é determinado pelo formato de saída do carimbo de data/hora para a sessão atual e pelo tipo de dados do valor do carimbo de data/hora retornado.
Para a versão de 3 argumentos, a hora local no resultado representa o mesmo momento no tempo que a hora local de entrada no fuso horário de entrada, mas no fuso horário de destino.
Para a versão de 2 argumentos, o argumento source_timestamp normalmente inclui o fuso horário. Se o valor for do tipo TIMESTAMP_TZ, o fuso horário é tirado de seu valor. Caso contrário, é utilizado o fuso horário da sessão atual.
Para source_tz e target_tz, é possível especificar um nome de fuso horário ou um nome de link do lançamento 2025b do banco de dados de fuso horário IANA (por exemplo, America/Los_Angeles, Europe/London, UTC, Etc/GMT e assim por diante).
Nota
- Os nomes de fuso horário diferenciam maiúsculas de minúsculas e precisam ser colocados entre aspas simples (por exemplo, 'UTC').
- O Snowflake não oferece suporte à maioria das abreviações de fuso horário (por exemplo, PDT, EST etc.) porque uma determinada abreviação pode se referir a um dos vários fusos horários diferentes. Por exemplo, CST pode se referir ao Horário Padrão Central na América do Norte (UTC-6), ao Horário Padrão de Cuba (UTC-5) e ao Horário Padrão da China (UTC8).

Exemplos¶

Para usar o formato de saída de carimbo de data/hora padrão para os carimbos de data/hora retornados nos exemplos, remova a definição do parâmetro TIMESTAMP_OUTPUT_FORMAT na sessão atual:

ALTER SESSION UNSET TIMESTAMP_OUTPUT_FORMAT;

Exemplos que especificam um fuso horário de origem¶

Os exemplos a seguir usam a versão de 3 argumentos da função CONVERT_TIMEZONE e especificam um valor source_tz. Esses exemplos retornam valores TIMESTAMP_NTZ.

Converter a hora local em Los Angeles para a hora local correspondente em Nova York:

SELECT CONVERT_TIMEZONE(
  'America/Los_Angeles',
  'America/New_York',
  '2024-01-01 14:00:00'::TIMESTAMP_NTZ
) AS conv;

+-------------------------+
| CONV                    |
|-------------------------|
| 2024-01-01 17:00:00.000 |
+-------------------------+

Converter uma hora local em Varsóvia para o horário correspondente em UTC:

SELECT CONVERT_TIMEZONE(
  'Europe/Warsaw',
  'UTC',
  '2024-01-01 00:00:00'::TIMESTAMP_NTZ
) AS conv;

+-------------------------+
| CONV                    |
|-------------------------|
| 2023-12-31 23:00:00.000 |
+-------------------------+

Exemplos que não especificam um fuso horário de origem¶

Os exemplos a seguir usam a versão de 2 argumentos da função CONVERT_TIMEZONE. Esses exemplos retornam valores TIMESTAMP_TZ. Portanto, os valores retornados incluem um deslocamento que mostra a diferença entre o fuso horário do carimbo de data/hora e o fuso horário Tempo Universal Coordenado (UTC). Por exemplo, o fuso horário America/Los_Angeles tem um deslocamento de -0700, indicando que está sete horas atrás do UTC.

Converter uma cadeia de caracteres especificando um valor TIMESTAMP_TZ para um fuso horário diferente:

SELECT CONVERT_TIMEZONE(
  'America/Los_Angeles',
  '2024-04-05 12:00:00 +02:00'
) AS time_in_la;

+-------------------------------+
| TIME_IN_LA                    |
|-------------------------------|
| 2024-04-05 03:00:00.000 -0700 |
+-------------------------------+

Visualize a hora local atual em diferentes fusos horários:

SELECT
  CURRENT_TIMESTAMP() AS now_in_la,
  CONVERT_TIMEZONE('America/New_York', CURRENT_TIMESTAMP()) AS now_in_nyc,
  CONVERT_TIMEZONE('Europe/Paris', CURRENT_TIMESTAMP()) AS now_in_paris,
  CONVERT_TIMEZONE('Asia/Tokyo', CURRENT_TIMESTAMP()) AS now_in_tokyo;

+-------------------------------+-------------------------------+-------------------------------+-------------------------------+
| NOW_IN_LA                     | NOW_IN_NYC                    | NOW_IN_PARIS                  | NOW_IN_TOKYO                  |
|-------------------------------+-------------------------------+-------------------------------+-------------------------------|
| 2024-06-12 08:52:53.114 -0700 | 2024-06-12 11:52:53.114 -0400 | 2024-06-12 17:52:53.114 +0200 | 2024-06-13 00:52:53.114 +0900 |
+-------------------------------+-------------------------------+-------------------------------+-------------------------------+