Documentation

    time_bucket

    Round a date or timestamp down to the start of a fixed-width bucket, such as every 2 days. Buckets count from 2000-01-03, or from 2000-01-01 for month and year buckets, unless you pass your own origin.

    Try an expression

    In Formula, enter the expression and set Output type to DATE.

    Expression

    time_bucket(INTERVAL '2 days', DATE '2024-01-04')

    Result

    2024-01-03

    To use your own data, replace the example values with column names. Keep format strings and other options as written.

    Arguments and types

    time_bucket(bucket_width, timestamp, origin)
    bucket_width
    Interval
    timestamp
    Date, Timestamp
    origin
    Date, Interval, Timestamp, Text
    Supported signatures (10)
    time_bucket(bucket_width: INTERVAL, timestamp: DATE) → DATE
    time_bucket(bucket_width: INTERVAL, timestamp: DATE, origin: DATE) → DATE
    time_bucket(bucket_width: INTERVAL, timestamp: DATE, origin: INTERVAL) → DATE
    time_bucket(bucket_width: INTERVAL, timestamp: TIMESTAMP WITH TIME ZONE) → TIMESTAMP WITH TIME ZONE
    time_bucket(bucket_width: INTERVAL, timestamp: TIMESTAMP WITH TIME ZONE, origin: INTERVAL) → TIMESTAMP WITH TIME ZONE
    time_bucket(bucket_width: INTERVAL, timestamp: TIMESTAMP WITH TIME ZONE, origin: TIMESTAMP WITH TIME ZONE) → TIMESTAMP WITH TIME ZONE
    time_bucket(bucket_width: INTERVAL, timestamp: TIMESTAMP WITH TIME ZONE, origin: VARCHAR) → TIMESTAMP WITH TIME ZONE
    time_bucket(bucket_width: INTERVAL, timestamp: TIMESTAMP) → TIMESTAMP
    time_bucket(bucket_width: INTERVAL, timestamp: TIMESTAMP, origin: INTERVAL) → TIMESTAMP
    time_bucket(bucket_width: INTERVAL, timestamp: TIMESTAMP, origin: TIMESTAMP) → TIMESTAMP

    The result type can depend on the input types. See DuckDB for the full argument rules.

    Things to know

    If the first argument is missing, the result is NULL.

    Browse dates & timesDuckDB documentation

    Function metadata from DuckDB, used under the MIT license.