Skip to main content
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

OperatorWhat it groups by
$termsDistinct field values
$rangeExplicit from / to ranges
$histogramFixed numeric intervals
$dateHistogramFixed date/time intervals
$facetHierarchical 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.