time_bucket 関数

適用対象:チェックマーク、はい 、Databricks、SQL 、はい 、Databricks、ランタイム19以上

タイムスタンプが当てはまる固定幅の時間バケットの開始点を原点にアライメントして返します。

構文

time_bucket(bucketSize, ts [, origin])

引数

  • bucketSize:各バケットのサイズを指定する INTERVAL 定数式です。 日中および年・月の間隔に対応しています。 は正でゼロでなければなりません。
  • tsバケツへの表現 TIMESTAMP または TIMESTAMP_NTZ 。
  • origin:バケットグリッドのアライメントアンカーを定義するオプションの TIMESTAMP または TIMESTAMP_NTZ 定数式。 既定値は 1970-01-01 00:00:00 です。 tsと同じタイプに違いない。

返品

tsと同じタイプの値(TIMESTAMPまたはTIMESTAMP_NTZ)。 値はtsを含む半開バケット[start, start + bucketSize)の開始点です。 開始は常に ts以下であり、次のバケット境界(start + bucketSize)は厳密に tsより大きい。

ノート

  • time_bucket 時間軸を連続した重ならない bucketSizeの区間に分割し、それぞれ originに固定します。 tsを含む区間の開始点を返します。
  • origin tsに先行する必要はありません。 バケットグリッドのアラインメントを定義するだけです。 グリッドは originから両方向に無限に伸びています。
  • TIMESTAMP_NTZはUTCでバケツtime_bucket。 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