time_bucket 函數

適用於：勾選標記為是 Databricks SQL 勾選為 Databricks 執行時間 19 及以上

回傳時間戳記所落入的固定寬度時間桶的起點，並對齊到原點。

語法

time_bucket(bucketSize, ts [, origin])

引數

  • bucketSize： 一個 INTERVAL 常數表達式，指定每個桶的大小。 支援白天及年月的間隔。 必須是正且非零。
  • ts： A TIMESTAMP 或 TIMESTAMP_NTZ 表達式轉為桶。
  • origin： 一個可選 TIMESTAMP 或 TIMESTAMP_NTZ 常數表達式，用以定義桶格的對齊錨點。 預設為 1970-01-01 00:00:00。 必須與 相同型態 ts。

Returns

與（TIMESTAMP或TIMESTAMP_NTZ）型同ts的值。 該值為包含 ts的半開桶[start, start + bucketSize)的起始值。 起始值總是小於或等 ts於 ，且下一個桶邊界（start + bucketSize）嚴格大於 ts。

Notes

  • time_bucket 將時間軸分割為連續且不重疊的區 bucketSize間，大小為 ，錨定於 origin。 它回傳包含 ts的區間起始點。
  • origin 不必先於 ts。 它只定義了桶格的對齊。 格子從 向兩個方向無限延伸。origin
  • 對於 TIMESTAMP_NTZ， time_bucket UTC 中的桶。 對於 TIMESTAMP，年月間隔桶及日-時間間隔桶的日曆-日組成部分對應會話時區。
  • 若任意參數為 NULL，結果為 NULL。
  • 用於 date_trunc 與日曆對齊的邊界，例如依月曆分組。 當桶寬度或對齊是使用者定義的時才會使用 time_bucket 。

常見錯誤條件

範例

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