BUCKET

Maps a supported value to one of a fixed number of hash buckets. BUCKET() returns a deterministic UInt32 value from 0 through bucket_count - 1 and is designed for PARTITION BY and CLUSTER BY expressions.

Syntax

BUCKET(<bucket_count>, <value>)

Arguments

The function returns NULL when either argument is NULL.

Examples

-- Returns an integer from 0 through 15.
SELECT BUCKET(16, 'customer-123');

Use a fixed bucket count to partition a high-cardinality key:

CREATE TABLE customer_events (
    customer_id BIGINT,
    event_time  TIMESTAMP,
    payload     VARIANT
)
PARTITION BY (BUCKET(32, customer_id));

For distributed ingestion, rows with the same evaluated partition value can be routed to the same writer:

CREATE TABLE customer_events_distributed (
    customer_id BIGINT,
    event_time  TIMESTAMP
)
PARTITION BY (BUCKET(32, customer_id))
WRITE_DISTRIBUTION_MODE = 'hash';

WRITE_DISTRIBUTION_MODE = 'hash' requires a PARTITION BY clause.