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。

备注

  • 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