time_bucket-Funktion

Gilt für:Haken markiert ja Databricks SQL Haken markiert ja Databricks Runtime 19 und höher

Gibt den Anfang des Zeitbuckets mit fester Breite zurück, in den ein Zeitstempel fällt, ausgerichtet auf einen Ursprung.

Syntax

time_bucket(bucketSize, ts [, origin])

Argumente

  • bucketSize: Ein konstanter Ausdruck, der die Größe jedes Eimers INTERVAL angibt. Unterstützt Tages- und Jahres-Monatsintervalle. Muss positiv und nicht null sein.
  • ts: A oder Ausdruck TIMESTAMP_NTZ zu EimerTIMESTAMP.
  • origin: Ein optionaler TIMESTAMP oder TIMESTAMP_NTZ konstanter Ausdruck, der den Ausrichtungsanker des Eimerrasters definiert. Wird standardmäßig auf 1970-01-01 00:00:00 festgelegt. Muss vom gleichen Typ tswie sein.

Rückkehr

Ein Wert desselben Typs wie ts (TIMESTAMP oder TIMESTAMP_NTZ). Der Wert ist der Anfang des halboffenen Eimers [start, start + bucketSize) , der enthält ts. Der Anfang ist immer kleiner als oder gleich , tsund der nächste Eimerrand (start + bucketSize) ist streng größer als ts.

Notizen

  • time_bucket teilt die Zeitachse in aufeinanderfolgende, nicht überlappende Intervalle der Größe bucketSize, verankert bei origin. Sie gibt den Anfang des Intervalls zurück, das enthält ts.
  • origin muss nicht vor tsgestellt werden. Es definiert nur die Ausrichtung des Eimergitters. Das Gitter erstreckt sich unendlich in beide Richtungen von .origin
  • Für TIMESTAMP_NTZ, time_bucket Buckets in UTC. Für TIMESTAMP, Jahr-Monat-Intervall-Buckets und die Kalendertage-Komponenten der Tagesintervall-Buckets entsprechen der Sitzungszeitzone.
  • Wenn ein Argument ist NULL, ist das Ergebnis NULL.
  • Verwenden date_trunc Sie für kalenderausgerichtete Grenzen, wie z. B. die Gruppierung nach Kalendermonaten. Verwenden Sie, time_bucket wenn die Bucket-Breite oder -Ausrichtung benutzerdefiniert ist.

Häufige Fehlerbedingungen

Beispiele

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