Overview

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#

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.