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.