Overview - Upstash Documentation

Bucket aggregations group matching documents into buckets. Use bucket aggregations when you want segmented analytics (for example by category, price tier, or time window).

Available Operators

Operator	What it groups by
`$terms`	Distinct field values
`$range`	Explicit `from` / `to` ranges
`$histogram`	Fixed numeric intervals
`$dateHistogram`	Fixed date/time intervals
`$facet`	Hierarchical FACET paths

Input Format

Every bucket operator takes an object with a field property and operator-specific parameters: $terms — group by distinct values:

{"by_category": {"$terms": {"field": "category", "size": 10}}}

$range — custom range buckets:

{"price_ranges": {"$range": {"field": "price", "ranges": [{"to": 50}, {"from": 50, "to": 100}, {"from": 100}]}}}

$histogram — fixed numeric intervals:

{"price_buckets": {"$histogram": {"field": "price", "interval": 10}}}

$dateHistogram — fixed time intervals:

{"by_month": {"$dateHistogram": {"field": "createdAt", "fixedInterval": "30d"}}}

Behavior Notes

Bucket operators can contain nested $aggs for per-bucket metrics.
$terms, $range, $histogram, and $dateHistogram support nested $aggs.
$facet does not support nested $aggs and cannot be used as a sub-aggregation.

​Available Operators

​Input Format

​Behavior Notes

Available Operators

Input Format

Behavior Notes