time_bucket Função

Aplica-se a:com marca de verificação sim Databricks SQL marcado sim Databricks Runtime 19 e acima

Retorna o início do balde de tempo de largura fixa em que um carimbo de tempo se encaixa, alinhado a uma origem.

Sintaxe

time_bucket(bucketSize, ts [, origin])

Argumentos

  • bucketSize: Uma INTERVAL expressão constante que especifica o tamanho de cada balde. Suporta intervalos diurnos e de um ano-mês. Deve ser positivo e diferente de zero.
  • ts: A ou TIMESTAMP_NTZ expressão para bucketTIMESTAMP.
  • origin: Uma expressão opcional TIMESTAMP ou TIMESTAMP_NTZ constante que define a âncora de alinhamento da grade de balde. Usa 1970-01-01 00:00:00 como padrão. Deve ser do mesmo tipo que ts.

Returns

Um valor do mesmo tipo que ts (TIMESTAMP ou TIMESTAMP_NTZ). O valor é o início do balde [start, start + bucketSize) semiaberto que contém ts. O início é sempre menor ou igual a ts, e a próxima fronteira do balde (start + bucketSize) é estritamente maior que ts.

Notas

  • time_bucket divide o eixo de tempo em intervalos consecutivos, não sobrepostos, de tamanho bucketSize, ancorados em origin. Ele retorna o início do intervalo que contém ts.
  • origin não precisa preceder ts. Ela define apenas o alinhamento da grade do balde. A grade se estende infinitamente em ambas as direções a partir originde .
  • Para TIMESTAMP_NTZ, time_bucket baldes em UTC. Para TIMESTAMP, os segmentos de intervalo ano-mês e os componentes de dia do calendário dos baldes de intervalo diurno-horário alinham-se ao fuso horário da sessão.
  • Se qualquer argumento for NULL, o resultado é NULL.
  • Use date_trunc para limites alinhados ao calendário, como agrupar por mês do calendário. Use time_bucket quando a largura ou alinhamento do balde for definido pelo usuário.

Condições de erro comuns

Exemplos

-- 15-minute buckets (default origin at epoch)
> SELECT time_bucket(INTERVAL '15' MINUTE, TIMESTAMP '2024-01-01 11:27:00');
 2024-01-01 11:15:00

-- 1-hour buckets
> SELECT time_bucket(INTERVAL '1' HOUR, TIMESTAMP '2024-01-01 11:27:00');
 2024-01-01 11:00:00

-- Custom origin shifts bucket alignment to :05 past the hour
> SELECT time_bucket(INTERVAL '1' HOUR, TIMESTAMP '2024-01-01 11:27:00', TIMESTAMP '1970-01-01 00:05:00');
 2024-01-01 11:05:00

-- TIMESTAMP_NTZ variant
> SELECT time_bucket(INTERVAL '15' MINUTE, TIMESTAMP_NTZ '2024-01-01 11:27:00');
 2024-01-01 11:15:00

-- ts exactly on a bucket boundary returns itself
> SELECT time_bucket(INTERVAL '15' MINUTE, TIMESTAMP '2024-01-01 11:15:00');
 2024-01-01 11:15:00

-- Origin after ts: grid extends backward
> SELECT time_bucket(INTERVAL '1' HOUR, TIMESTAMP '2024-01-01 11:27:00', TIMESTAMP '2025-01-01 00:30:00');
 2024-01-01 10:30:00

-- Monthly buckets (default epoch origin: 1st of month)
> SELECT time_bucket(INTERVAL '1' MONTH, TIMESTAMP '2024-03-15 11:27:00');
 2024-03-01 00:00:00

-- Quarterly buckets
> SELECT time_bucket(INTERVAL '3' MONTH, TIMESTAMP '2024-05-15 10:00:00');
 2024-04-01 00:00:00

-- Monthly buckets with origin on the 15th
> SELECT time_bucket(INTERVAL '1' MONTH, TIMESTAMP '2024-03-20 09:00:00', TIMESTAMP '1970-01-15 00:00:00');
 2024-03-15 00:00:00

-- Origin on 31st: day clamping in short months
> SELECT time_bucket(INTERVAL '1' MONTH, TIMESTAMP '2024-03-01 12:00:00', TIMESTAMP '1970-01-31 00:00:00');
 2024-02-29 00:00:00

-- Zero bucket width is rejected
> SELECT time_bucket(INTERVAL '0' SECOND, TIMESTAMP '2024-01-01 11:00:00');
 [DATATYPE_MISMATCH.VALUE_OUT_OF_RANGE] The bucketSize must be between (0, inf) (current value = INTERVAL '00' SECOND).
  • Last updated on