Categorias:

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

TO_TIME , TIME

Converte uma expressão de entrada em uma hora. Se a entrada for NULL, ela retorna NULL.

Consulte também:

TRY_TO_TIME

Sintaxe

TO_TIME( <string_expr> [, <format> ] )
TO_TIME( <timestamp_expr> )
TO_TIME( '<integer>' )
TO_TIME( <variant_expr> )

TIME( <string_expr> )
TIME( <timestamp_expr> )
TIME( '<integer>' )
TIME( <variant_expr> )
Copy

Argumentos

Obrigatório:

string_expr ou timestamp_expr ou variant_expr ou integer

Expressão a ser convertida em uma hora:

  • Para string_expr, o resultado da conversão da cadeia de caracteres em uma hora.

  • Para timestamp_expr, a parte da hora do valor de entrada.

  • Para 'integer' (uma cadeia de caracteres contendo um número inteiro), o inteiro é tratado como um número de segundos, milissegundos, microssegundos ou nanossegundos após o início da época Unix. Para obter mais detalhes, consulte as Notas de uso abaixo.

    Para esse carimbo de data/hora, a função recebe o número de segundos após o início da época Unix. A função realiza uma operação módulo para obter o resto da divisão desse número pelo número de segundos em um dia (86400):

    number_of_seconds % 86400

    A função interpreta esse restante como o número de segundos após a meia-noite.

    Por exemplo, suponha que o valor seja 31536002789.

    1. Com base na magnitude desse valor, a função usa milissegundos como unidade de tempo e determina que o valor representa 1971-01-01 00:00:02.789.

    2. A função recebe o número de segundos após a época Unix para esse valor (31536002).

    3. A função obtém o resto da divisão desse número pelo número de segundos em um dia (31536002 % 86400).

    4. A função usa o resto (2) como o número de segundos após a meia-noite. O valor resultante é 00:00:02.

    Nota

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

  • Para variant_expr:

    • Se a variante contiver uma cadeia de caracteres no formato TIME (‘HH:MI:SS’), é realizada uma conversão de cadeia de caracteres.

    • Se a variante contiver uma cadeia de caracteres no formato INTEGER, uma conversão de cadeia de caracteres é realizada e o valor é tratado como o número de segundos desde a meia-noite (módulo 86400, se necessário).

    • Se a variante contiver um valor nulo JSON, a saída será NULL.

Para todos os outros valores, é gerado um erro de conversão.

Opcional:

format

Especificador do formato de hora para string_expr ou AUTO, que especifica que o Snowflake deve detectar automaticamente o formato a ser utilizado. Para obter mais informações, consulte Formatos de data e hora em funções de conversão.

Padrão: valor atual do parâmetro de sessão TIME_INPUT_FORMAT (geralmente AUTO)

Retornos

O tipo de dados do valor retornado é TIME.

Notas de uso

  • Se o formato do parâmetro de entrada for uma cadeia de caracteres que contenha um número inteiro, a unidade de medida do valor (segundos, microssegundos, milissegundos ou nanossegundos) será determinada da seguinte forma:

  • 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.

    Cuidado

    Atualmente, valores negativos são sempre tratados como segundos. Por exemplo, -31536000000000000000 é tratado como um número de segundos antes do ano 1970, embora sua escala implique que ele se destina a ser usado como nanossegundos.

    Este comportamento pode mudar no futuro.

    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.

  • Ao contrário da função TO_TIME, a função TIME não oferece suporte ao parâmetro opcional format.

Exemplos

Estes exemplos demonstram a função TO_TIME.

SELECT TO_TIME('13:30:00'), TIME('13:30:00');
+---------------------+------------------+
| TO_TIME('13:30:00') | TIME('13:30:00') |
|---------------------+------------------|
| 13:30:00            | 13:30:00         |
+---------------------+------------------+
Copy
SELECT TO_TIME('13:30:00.000'), TIME('13:30:00.000');
+-------------------------+----------------------+
| TO_TIME('13:30:00.000') | TIME('13:30:00.000') |
|-------------------------+----------------------|
| 13:30:00                | 13:30:00             |
+-------------------------+----------------------+
Copy

Este exemplo mostra como usar a função TO_TIME para processar separadores de campo que não sejam os dois-pontos padrão (este exemplo usa o caractere de ponto como separador entre horas e minutos, e entre minutos e segundos):

SELECT TO_TIME('11.15.00', 'HH24.MI.SS');
+-----------------------------------+
| TO_TIME('11.15.00', 'HH24.MI.SS') |
|-----------------------------------|
| 11:15:00                          |
+-----------------------------------+
Copy

Este exemplo demonstra como a função TO_TIME interpreta uma cadeia de caracteres contendo um valor inteiro:

CREATE TABLE demo1_time (
    description VARCHAR,
    value VARCHAR -- yes, string rather than bigint
    );
+----------------------------------------+
| status                                 |
|----------------------------------------|
| Table DEMO1_TIME successfully created. |
+----------------------------------------+
INSERT INTO demo1_time (description, value) VALUES
   ('Seconds',      '31536001'),
   ('Milliseconds', '31536002400'),
   ('Microseconds', '31536003600000'),
   ('Nanoseconds',  '31536004900000000')
   ;
+-------------------------+
| number of rows inserted |
|-------------------------|
|                       4 |
+-------------------------+
Copy
SELECT
       description,
       value,
       TO_TIMESTAMP(value),
       TO_TIME(value)
    FROM demo1_time
    ORDER BY value
    ;
+--------------+-------------------+-------------------------+----------------+
| DESCRIPTION  | VALUE             | TO_TIMESTAMP(VALUE)     | TO_TIME(VALUE) |
|--------------+-------------------+-------------------------+----------------|
| Seconds      | 31536001          | 1971-01-01 00:00:01.000 | 00:00:01       |
| Milliseconds | 31536002400       | 1971-01-01 00:00:02.400 | 00:00:02       |
| Microseconds | 31536003600000    | 1971-01-01 00:00:03.600 | 00:00:03       |
| Nanoseconds  | 31536004900000000 | 1971-01-01 00:00:04.900 | 00:00:04       |
+--------------+-------------------+-------------------------+----------------+
Copy