time_bucket функция

Применимо к:отмечен галочкой «да» Databricks SQL отмечен «да» Databricks Runtime 19 и выше

Возвращает начало фиксированного временного кокета, в который попадает временная метка, выравнивая с началом координат.

Синтаксис

time_bucket(bucketSize, ts [, origin])

Аргументы

  • bucketSize: Постоянное INTERVAL выражение, указывающее размер каждого бакета. Поддерживает дневные и месячные интервалы. Должно быть положительным и ненулевым.
  • ts: A TIMESTAMP или TIMESTAMP_NTZ выражение к ведрю.
  • origin: Необязательное TIMESTAMP или TIMESTAMP_NTZ постоянное выражение, определяющее якорь выравнивания сетки bucket. По умолчанию — 1970-01-01 00:00:00. Должно быть того же типа, что tsи .

Returns

Значение того же типа, что ts и (TIMESTAMP или TIMESTAMP_NTZ). Значение — это начало наполовину открытого кокета [start, start + bucketSize) , содержащего ts. Начало всегда меньше или равно ts, а следующая граница ведра (start + bucketSize) строго больше ts.

Заметки

  • time_bucket делит ось времени на последовательные, не перекрывающиеся интервалы размера bucketSize, закреплённые в origin. Он возвращает начало интервала, который содержит ts.
  • origin не обязательно предшествовать ts. Он определяет только выравнивание сетки bucket grid. Сетка простирается бесконечно в обоих направлениях от origin.
  • Для TIMESTAMP_NTZ, time_bucket ведра в UTC. Для TIMESTAMP, кокеты с интервалом года-месяц и компоненты календарных дней в сегментах дневного интервала совпадают с часовым поясом сессии.
  • Если любой аргумент равен NULL, результат — NULL.
  • Используйте date_trunc для границ, выровненных по календарю, например, группировки по календарным месяцам. Используйте time_bucket тогда, когда ширина или выравнивание ведра определяются пользовательским способом.

Распространенные условия ошибки

Examples

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