Categorias:

Funções de conversão , Funções de data e hora

TO_TIMESTAMP / TO_TIMESTAMP_*

Converte uma expressão de entrada no carimbo de data/hora correspondente:

  • TO_TIMESTAMP_LTZ (carimbo de data/hora com fuso horário local)

  • TO_TIMESTAMP_NTZ (carimbo de data/hora sem fuso horário)

  • TO_TIMESTAMP_TZ (carimbo de data/hora com fuso horário)

Nota

TO_TIMESTAMP faz o mapeamento para uma das outras funções de carimbo de data/hora, com base no parâmetro de sessão TIMESTAMP_TYPE_MAPPING. O parâmetro padrão é TIMESTAMP_NTZ, de forma que TO_TIMESTAMP faz o mapeamento para TO_TIMESTAMP_NTZ por padrão.

Consulte também:

TRY_TO_TIMESTAMP / TRY_TO_TIMESTAMP_* ,

AS_TIMESTAMP_* , IS_TIMESTAMP_* ,

TO_DATE , DATE , TO_TIME , TIME

Sintaxe

timestampFunction ( <numeric_expr> [ , <scale> ] )

timestampFunction ( <date_expr> )

timestampFunction ( <timestamp_expr> )

timestampFunction ( <string_expr> [ , <format> ] )

timestampFunction ( '<integer>' )

timestampFunction ( <variant_expr> )
Copy

Onde:

timestampFunction ::=
    TO_TIMESTAMP | TO_TIMESTAMP_LTZ | TO_TIMESTAMP_NTZ | TO_TIMESTAMP_TZ
Copy

Argumentos

Obrigatório:

Uma das opções:

numeric_expr

Um número de segundos (se escala = 0 ou está ausente) ou frações de segundo (por exemplo, milissegundos ou nanossegundos) desde o início da época Unix (1970-01-01 00:00:00 UTC). Se uma expressão decimal de números não inteiros for inserida, a escala do resultado é herdada.

date_expr

Uma data a ser convertida em um carimbo de data/hora.

timestamp_expr

Um carimbo de data/hora a ser convertido em outro carimbo de data/hora (por exemplo, conversão de TIMESTAMP_LTZ para TIMESTAMP_NTZ).

string_expr

Cadeia de caracteres da qual se pode extrair um carimbo de data/hora, por exemplo ‘2019-01-31 01:02:03.004’.

'integer'

Uma expressão que avalia como uma cadeia de caracteres contendo um número inteiro, por exemplo ‘15000000’. Dependendo da magnitude da cadeia de caracteres, ela pode ser interpretada como segundos, milissegundos, microssegundos ou nanossegundos. Para obter mais detalhes, consulte as Notas de uso abaixo.

Nota

O uso de números inteiros cotados como entradas é obsoleto.

variant_expr

Uma expressão do tipo VARIANT. O VARIANT deve conter um dos seguintes:

  • Uma cadeia de caracteres da qual se pode extrair um carimbo de data/hora.

  • Um carimbo de data/hora.

  • Um número inteiro de segundos ou milissegundos.

  • Uma cadeia de caracteres contendo um número inteiro de segundos ou milissegundos.

Embora TO_TIMESTAMP aceite um valor DATE, não aceita um DATE dentro de um VARIANT.

Opcional:

format

Especificador do formato (somente para string_expr). Para obter mais informações, consulte Formatos de data e hora em Funções de conversão.

O valor padrão é o valor atual do parâmetro TIMESTAMP_INPUT_FORMAT (geralmente AUTO).

scale

Especificador de escala (somente para numeric_expr). Se especificado, define a escala dos números fornecidos. Por exemplo:

  • Por segundos, escala = 0.

  • Para milissegundos, escala = 3.

  • Para nanossegundos, escala = 9.

Retornos

O tipo de dados do valor retornado é um dos tipos de dados de TIMESTAMP. Por padrão, o tipo de dados é TIMESTAMP_NTZ. Você pode alterar isso definindo o parâmetro de sessão TIMESTAMP_TYPE_MAPPING.

Notas de uso

  • Esta família de funções retorna valores de carimbo de data/hora, especificamente:

    • Para entrada NULL, o resultado será NULL.

    • Para string_expr: carimbo de data/hora representado por uma determinada cadeia de caracteres. Se a cadeia de caracteres não tiver um componente de hora, será usada a meia-noite.

    • Para date_expr: será utilizado o carimbo de data/hora que representa a meia-noite de um determinado dia, de acordo com a semântica de carimbo de data/hora específica (NTZ/LTZ/TZ).

    • Para timestamp_expr: um carimbo de data/hora possivelmente diferente do carimbo de data/hora de origem.

    • Para numeric_expr: um carimbo de data/hora representando o número de segundos (ou frações de segundo) fornecido pelo usuário. Note a hora UTC é sempre usada para criar o resultado.

    • Para variant_expr:

      • Se a variante contiver valor JSON nulo, o resultado será NULL.

      • Se a variante contiver um valor de carimbo de data/hora do mesmo tipo do resultado, este valor será preservado dessa maneira.

      • Se a variante contiver um valor de carimbo de data/hora de tipo diferente, a conversão será feita da mesma maneira que timestamp_expr.

      • Se a variante contiver uma cadeia de caracteres, a conversão de um valor de cadeia de caracteres será realizada (usando o formato automático).

      • Se a variante contiver um número, será realizada a conversão como se fosse de numeric_expr.

        Nota

        Quando um valor INTEGER é convertido diretamente em TIMESTAMP_NTZ, o número inteiro é tratado como o número de segundos desde o início da época Linux, e o fuso horário local não é levado em conta. (Para obter mais detalhes, consulte TO_TIMESTAMP / TO_TIMESTAMP_*.) No entanto, se o valor INTEGER for armazenado dentro de um valor VARIANT, por exemplo, como mostrado abaixo, então a conversão é indireta e é afetada pelo fuso horário local, mesmo que o resultado final seja TIMESTAMP_NTZ:

        select to_timestamp(parse_json(31000000));
select parse_json(31000000)::timestamp_ntz;
        Copy

        Para fazer a conversão independentemente do fuso horário local, acrescente uma conversão explícita ao número inteiro na expressão, como mostrado abaixo:

        select to_timestamp(parse_json(31000000)::int);
select parse_json(31000000)::int::timestamp_ntz;
        Copy

        Isso se aplica tanto para converter para TIMESTAMP_NTZ quanto para chamar a função TO_TIMESTAMP_NTZ(). Isso também se aplica ao chamar TO_TIMESTAMP() quando o parâmetro TIMESTAMP_TYPE_MAPPING é definido como TIMESTAMP_NTZ.

        Para um exemplo com saída, consulte os exemplos no final fim tópico.

    • Se a conversão não for possível, um erro é retornado.

  • Se o formato do parâmetro de entrada for uma cadeia de caracteres que contenha um número inteiro:

    • Depois que a cadeia de caracteres é convertida em um inteiro, o inteiro é tratado como um número de segundos, milissegundos, microssegundos ou nanossegundos após o início da época Unix (1970-01-01 00:00:00.000000000 UTC).

      • Se o número inteiro for inferior a 31536000000 (o número de milissegundos em um ano), então o valor é tratado como um número de segundos.

      • Se o valor for maior ou igual a 31536000000 e menor que 31536000000000, então o valor é tratado como milissegundos.

      • Se o valor for maior ou igual a 31536000000000 e menor que 31536000000000000, então o valor é tratado como microssegundos.

      • Se o valor for maior ou igual a 31536000000000000, então o valor é tratado como nanossegundos.

      Nota

      Aviso de descontinuação: Versões futuras do Snowflake podem interpretar automaticamente valores inteiros de cadeia de caracteres como segundos, em vez de milissegundos, microssegundos ou nanossegundos. O Snowflake recomenda chamar TO_DATE, TO_TIME ou TO_TIMESTAMP com cadeias de caracteres que contenham inteiros somente quando esses inteiros devam ser interpretados como segundos.

    • Se mais de uma linha for avaliada (por exemplo, se a entrada for o nome da coluna de uma tabela que contém mais de uma linha), cada valor será examinado independentemente para determinar se o valor representa segundos, milissegundos, microssegundos ou nanossegundos.

Exemplos

Isso mostra que TO_TIMESTAMP_TZ cria um carimbo de data/hora que contém um fuso horário da sessão, mas o valor de TO_TIMESTAMP_NTZ não tem um fuso horário:

ALTER SESSION SET TIMEZONE = 'America/Los_Angeles';
+----------------------------------+
| status                           |
|----------------------------------|
| Statement executed successfully. |
+----------------------------------+
SELECT TO_TIMESTAMP_TZ('2013-04-05 01:02:03');
+----------------------------------------+
| TO_TIMESTAMP_TZ('2013-04-05 01:02:03') |
|----------------------------------------|
| 2013-04-05 01:02:03.000 -0700          |
+----------------------------------------+

SELECT TO_TIMESTAMP_NTZ('2013-04-05 01:02:03');
+-----------------------------------------+
| TO_TIMESTAMP_NTZ('2013-04-05 01:02:03') |
|-----------------------------------------|
| 2013-04-05 01:02:03.000                 |
+-----------------------------------------+
Copy

Isso mostra como formatos diferentes podem influenciar a análise de uma data ambígua:

SELECT TO_TIMESTAMP_TZ('04/05/2013 01:02:03', 'mm/dd/yyyy hh24:mi:ss');
+-----------------------------------------------------------------+
| TO_TIMESTAMP_TZ('04/05/2013 01:02:03', 'MM/DD/YYYY HH24:MI:SS') |
|-----------------------------------------------------------------|
| 2013-04-05 01:02:03.000 -0700                                   |
+-----------------------------------------------------------------+

SELECT TO_TIMESTAMP_TZ('04/05/2013 01:02:03', 'dd/mm/yyyy hh24:mi:ss');
+-----------------------------------------------------------------+
| TO_TIMESTAMP_TZ('04/05/2013 01:02:03', 'DD/MM/YYYY HH24:MI:SS') |
|-----------------------------------------------------------------|
| 2013-05-04 01:02:03.000 -0700                                   |
+-----------------------------------------------------------------+
Copy

Isso mostra como usar uma entrada numérica que representa aproximadamente 40 anos a partir da meia-noite de 1.º de janeiro de 1970 (o início da EPOCH UNIX):

ALTER SESSION SET TIMESTAMP_OUTPUT_FORMAT = 'YYYY-MM-DD HH24:MI:SS.FF9 TZH:TZM';
+----------------------------------+
| status                           |
|----------------------------------|
| Statement executed successfully. |
+----------------------------------+
SELECT TO_TIMESTAMP_NTZ(40 * 365.25 * 86400);
+---------------------------------------+
| TO_TIMESTAMP_NTZ(40 * 365.25 * 86400) |
|---------------------------------------|
| 2010-01-01 00:00:00.000               |
+---------------------------------------+
Copy

Isto é semelhante ao anterior, mas fornece o valor em milissegundos, resultando em um valor de escala de 3:

ALTER SESSION SET TIMESTAMP_OUTPUT_FORMAT = 'YYYY-MM-DD HH24:MI:SS.FF9 TZH:TZM';
+----------------------------------+
| status                           |
|----------------------------------|
| Statement executed successfully. |
+----------------------------------+
SELECT TO_TIMESTAMP_NTZ(40 * 365.25 * 86400 * 1000 + 456, 3);
+-------------------------------------------------------+
| TO_TIMESTAMP_NTZ(40 * 365.25 * 86400 * 1000 + 456, 3) |
|-------------------------------------------------------|
| 2010-01-01 00:00:00.456                               |
+-------------------------------------------------------+
Copy

Este exemplo mostra como a função determina as unidades a usar (segundos, milissegundos, microssegundos ou nanossegundos) com base na magnitude do valor:

Crie e carregue a tabela com cadeias de caracteres contendo números inteiros dentro de diferentes faixas:

CREATE TABLE demo1 (
    description VARCHAR,
    value VARCHAR -- yes, string rather than bigint
    );

INSERT INTO demo1 (description, value) VALUES
   ('Seconds',      '31536000'),
   ('Milliseconds', '31536000000'),
   ('Microseconds', '31536000000000'),
   ('Nanoseconds',  '31536000000000000')
   ;
Copy

Passe as cadeias de caracteres para a função:

SELECT
       description,
       value,
       TO_TIMESTAMP(value),
       TO_DATE(value)
    FROM demo1
    ORDER BY value
    ;
+--------------+-------------------+-------------------------+----------------+
| DESCRIPTION  | VALUE             | TO_TIMESTAMP(VALUE)     | TO_DATE(VALUE) |
|--------------+-------------------+-------------------------+----------------|
| Seconds      | 31536000          | 1971-01-01 00:00:00.000 | 1971-01-01     |
| Milliseconds | 31536000000       | 1971-01-01 00:00:00.000 | 1971-01-01     |
| Microseconds | 31536000000000    | 1971-01-01 00:00:00.000 | 1971-01-01     |
| Nanoseconds  | 31536000000000000 | 1971-01-01 00:00:00.000 | 1971-01-01     |
+--------------+-------------------+-------------------------+----------------+
Copy

O exemplo a seguir mostra a diferença de comportamento entre o uso de um número inteiro e o uso de uma variante que contém um número inteiro:

SELECT 0::TIMESTAMP_NTZ, PARSE_JSON(0)::TIMESTAMP_NTZ, PARSE_JSON(0)::INT::TIMESTAMP_NTZ;
+-------------------------+------------------------------+-----------------------------------+
| 0::TIMESTAMP_NTZ        | PARSE_JSON(0)::TIMESTAMP_NTZ | PARSE_JSON(0)::INT::TIMESTAMP_NTZ |
|-------------------------+------------------------------+-----------------------------------|
| 1970-01-01 00:00:00.000 | 1969-12-31 16:00:00.000      | 1970-01-01 00:00:00.000           |
+-------------------------+------------------------------+-----------------------------------+
Copy
SELECT TO_TIMESTAMP_NTZ(0), TO_TIMESTAMP_NTZ(PARSE_JSON(0)), TO_TIMESTAMP_NTZ(PARSE_JSON(0)::INT);
+-------------------------+---------------------------------+--------------------------------------+
| TO_TIMESTAMP_NTZ(0)     | TO_TIMESTAMP_NTZ(PARSE_JSON(0)) | TO_TIMESTAMP_NTZ(PARSE_JSON(0)::INT) |
|-------------------------+---------------------------------+--------------------------------------|
| 1970-01-01 00:00:00.000 | 1969-12-31 16:00:00.000         | 1970-01-01 00:00:00.000              |
+-------------------------+---------------------------------+--------------------------------------+
Copy
Linguagem: Português