TO_TIME - MaxCompute: Central de Documentação do Alibaba Cloud

A função TO_TIME converte dados de hora de diversos tipos e formatos em um valor BIGINT em microssegundos. Ela possui quatro assinaturas, cada uma aceitando um tipo diferente de entrada.

Escolha a assinatura conforme o tipo de entrada:

Se a entrada for...	Use
Uma string de hora (ex.: `'13:24:33'`)	Assinatura 1: `TO_TIME(STRING, STRING)`
Valores separados de hora, minuto e segundo	Assinatura 2: `TO_TIME(BIGINT, BIGINT, BIGINT)`
Um valor TIMESTAMP (com conversão de fuso horário)	Assinatura 3: `TO_TIME(TIMESTAMP[, STRING])`
Um valor TIMESTAMP_NTZ (sem fuso horário)	Assinatura 4: `TO_TIME(TIMESTAMP_NTZ)`

Sintaxe

Assinatura 1: analisar uma string de hora

Analisa um valor STRING conforme um formato especificado e retorna um valor de hora BIGINT em microssegundos.

BIGINT TO_TIME(STRING <value>, STRING <format>)

-- Returns 48273000000.
SELECT TO_TIME('13:24:33', '%H:%M:%S');

Assinatura 2: construir a partir de hora, minuto e segundo

Constrói um valor de hora BIGINT em microssegundos com base em valores BIGINT individuais para horas, minutos e segundos.

BIGINT TO_TIME(BIGINT <hour>, BIGINT <minute>, BIGINT <second>)

-- Returns 55800000000.
SELECT TO_TIME(15, 30, 0);

Assinatura 3: extrair a parte da hora de um TIMESTAMP

Extrai a parte da hora de um valor TIMESTAMP em um fuso horário específico e retorna um valor de hora BIGINT em microssegundos. As partes referentes à data e aos nanossegundos são descartadas.

BIGINT TO_TIME(TIMESTAMP <timestamp>[, STRING <time_zone>])

-- Returns 55801123000.
SELECT TO_TIME(TIMESTAMP '2019-09-01 15:30:01.123');

Assinatura 4: extrair a parte da hora de um TIMESTAMP_NTZ

Extrai a parte da hora de um valor TIMESTAMP_NTZ (timestamp sem fuso horário) e retorna um valor de hora BIGINT em microssegundos. Não há conversão de fuso horário.

BIGINT TO_TIME(TIMESTAMP_NTZ <timestamp_ntz>)

-- Returns 55801123456.
SELECT TO_TIME(TIMESTAMP_NTZ '2025-09-01 15:30:01.123456');

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`value`	STRING	Sim	String de hora a ser analisada. Exemplo: `'15:20:23'`.
`format`	STRING	Sim	Padrão de formato correspondente à estrutura de `value`. Consulte Especificadores de formato.
`hour`	BIGINT	Sim	Componente da hora.
`minute`	BIGINT	Sim	Componente do minuto.
`second`	BIGINT	Sim	Componente do segundo.
`timestamp`	TIMESTAMP	Sim	Timestamp a ser convertido.
`time_zone`	STRING	Não	Fuso horário de destino para a conversão. O padrão é o fuso horário da sessão ou do projeto atual (UTC+08:00 se não houver alteração). Para valores compatíveis, consulte Lista de fusos horários.
`timestamp_ntz`	TIMESTAMP_NTZ	Sim	Timestamp sem fuso horário a ser convertido.

Especificadores de formato

O parâmetro format aceita os especificadores listados abaixo. Há suporte a duas famílias de estilos: strftime (%H, %M, %S) e Oracle (hh, mi, ss).

Especificador	Correspondência	Exemplo
`%H`, `HH`, `hh`	Hora (00–23)	`13`
`%M`, `MI`, `mi`	Minuto (00–59)	`24`
`%S`, `SS`, `ss`	Segundo (00–59)	`33`
`ff3`	Milissegundos (3 casas decimais)	`123` em `00.123`
`%E<N>S`	Segundos com precisão fracionária de `<N>` dígitos	`%E6S` corresponde a `33.123456`
`%E*S`	Segundos com precisão total de 6 casas decimais (detecção automática)	`33.123456`

Exemplos de formatos válidos: hh:mi:ss, HH:MI:SS, %H:%M:%S, %H:%M:%E6S, %H:%M:%E*S.

Valor retornado

Retorna um valor BIGINT em microssegundos.

Comportamento para NULL e erros:

Condição	Resultado
`value`, `timestamp` ou `timestamp_ntz` é NULL	Erro
Qualquer um entre `hour`, `minute` ou `second` é NULL	NULL
`format` é NULL ou inválido	NULL

Exemplos

Assinatura 1: TO_TIME(STRING, STRING)

Análise de strings de hora com formatos comuns:

-- Standard strftime format.
-- Returns 48273000000.
SELECT TO_TIME('13:24:33', '%H:%M:%S');

-- Oracle-style format.
-- Returns 46860000000.
SELECT TO_TIME('13:01:00', 'hh:mi:ss');

-- Hours and minutes only.
-- Returns 46860000000.
SELECT TO_TIME('13:01', 'hh:mi');

Análise de strings de hora com precisão inferior a um segundo:

-- Minutes and seconds only.
-- Returns 781000000.
SELECT TO_TIME('13:01', 'mi:ss');

-- ff3 matches milliseconds (3 decimal places).
-- Returns 781123000.
SELECT TO_TIME('13:01.123', 'mi:ss.ff3');

-- %E6S matches microseconds (6 decimal places).
-- Returns 48273123456.
SELECT TO_TIME('13:24:33.123456', '%H:%M:%E6S');

-- %E*S auto-detects fractional precision.
-- Returns 48273123456.
SELECT TO_TIME('13:24:33.123456', '%H:%M:%E*S');

Tratamento de formatos inválidos e entradas NULL:

-- %h is not a valid specifier; use %H.
-- Returns NULL.
SELECT TO_TIME('13:24:33', '%h:%m:%s');

-- NULL format returns NULL.
-- Returns NULL.
SELECT TO_TIME('13:24:33', NULL);

Assinatura 2: TO_TIME(BIGINT, BIGINT, BIGINT)

Construção de um valor de hora a partir de hora, minuto e segundo:

-- Returns 55800000000.
SELECT TO_TIME(15, 30, 0);

Chamadas com apenas dois argumentos retornam NULL:

-- Only two arguments are passed; does not match the three-argument signature.
-- Returns NULL.
SELECT TO_TIME(15, 30);

Entradas NULL retornam NULL:

-- Returns NULL.
SELECT TO_TIME(15, 30, NULL);

-- Returns NULL.
SELECT TO_TIME(15, NULL, 0);

-- Returns NULL.
SELECT TO_TIME(NULL, 30, 0);

Assinatura 3: TO_TIME(TIMESTAMP[, STRING])

Extração da parte da hora usando o fuso horário padrão:

-- Returns 55801123000.
SELECT TO_TIME(TIMESTAMP '2025-09-01 15:30:01.123');

Conversão do resultado para uma string de hora legível usando FORMAT_TIME:

-- Returns '15:30:01.123'.
SELECT FORMAT_TIME(TO_TIME(TIMESTAMP '2025-09-01 15:30:01.123'), "%H:%M:%S.ff3");

Especifique um fuso horário de destino:

-- Explicitly pass Asia/Shanghai.
-- Returns 55801123000.
SELECT TO_TIME(TIMESTAMP '2025-09-01 15:30:01.123', 'Asia/Shanghai');

Conversões entre fusos horários:

-- Tokyo is UTC+9, 1 hour ahead of Shanghai (UTC+8).
-- 15:30 in Shanghai -> 16:30 in Tokyo.
-- Returns 59401123456.
SELECT TO_TIME(TIMESTAMP '2025-09-01 15:30:01.123456', 'Asia/Tokyo');

-- Bangkok is UTC+7, 1 hour behind Shanghai.
-- 15:30 in Shanghai -> 14:30 in Bangkok.
-- Returns 52201123456.
SELECT TO_TIME(TIMESTAMP '2025-09-01 15:30:01.123456789', 'Asia/Bangkok');

Assinatura 4: TO_TIME(TIMESTAMP_NTZ)

O tipo TIMESTAMP_NTZ armazena um timestamp sem informações de fuso horário. A função TO_TIME extrai a parte da hora diretamente, sem conversões.

-- Returns 55801123456.
SELECT TO_TIME(TIMESTAMP_NTZ '2025-09-01 15:30:01.123456789');

Funções relacionadas

A função TO_TIME integra a família de funções de data e hora. Para outras funções de cálculo e conversão de tempo, consulte Funções de data e hora.

Para formatar o resultado BIGINT como uma string de hora legível, use FORMAT_TIME.