time_bucket Fonction

S’applique à :coché oui Databricks SQL coché oui Databricks Runtime 19 et supérieur

Retourne le début du compartiment temporel à largeur fixe dans lequel se trouve un horodatage, aligné sur une origine.

Syntaxe

time_bucket(bucketSize, ts [, origin])

Les arguments

  • bucketSize: Une INTERVAL expression constante qui spécifie la taille de chaque seau. Prend en charge les intervalles de jour et d’année-mois. Doit être positif et non nul.
  • ts: Expression de A ou TIMESTAMP_NTZ à bucketTIMESTAMP.
  • origin: Une expression optionnelle TIMESTAMP ou TIMESTAMP_NTZ constante qui définit l’ancrage d’alignement de la grille à seau. La valeur par défaut est 1970-01-01 00:00:00. Doit être du même type que ts.

Retours

Une valeur du même type que ts (TIMESTAMP ou TIMESTAMP_NTZ). La valeur est le début du seau [start, start + bucketSize) demi-ouvert qui contient ts. Le début est toujours inférieur ou égal à ts, et la frontière suivante du seau (start + bucketSize) est strictement supérieure à ts.

Remarques

  • time_bucket divise l’axe du temps en intervalles consécutifs et non chevauchants de taille bucketSize, ancrés en origin. Elle retourne le début de l’intervalle qui contient ts.
  • origin n’a pas besoin de précéder ts. Cela ne définit que l’alignement de la grille à seau. La grille s’étend à l’infini dans les deux directions à partir de origin.
  • Pour TIMESTAMP_NTZ, time_bucket des seaux dans UTC. Pour TIMESTAMP, les segments annuel-mois et les composantes jour du calendrier des intervalles jour-temps s’alignent avec le fuseau horaire de la session.
  • Si un argument est NULL, le résultat est NULL.
  • À utiliser date_trunc pour des limites alignées sur le calendrier, comme le regroupement par mois du calendrier. À utiliser time_bucket lorsque la largeur ou l’alignement du seau est défini par l’utilisateur.

Conditions d’erreur courantes

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