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

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.