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
`$composite`	Paginated combinations of several sources
`$facet`	Hierarchical FACET paths

Input Format

Most bucket operators take an object with a field property and operator-specific parameters. $composite instead takes a sources array, and each source specifies its own field. $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"}}}

$composite — paginated buckets across several sources:

{"by_category_and_price": {"$composite": {"size": 100, "sources": [{"category": {"$terms": {"field": "category"}}}, {"price": {"$histogram": {"field": "price", "interval": 10}}}]}}}

Behavior Notes

Bucket operators can contain nested $aggs for per-bucket metrics.
$terms, $range, $histogram, $dateHistogram, and $composite 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