Aggregation Reference

Terms & Composite Aggregations

Bucket aggregations group documents into buckets. terms is similar to GROUP BY.

// terms: group by field values
GET /orders/_search
{
  "size": 0,
  "aggs": {
    "by_status": {
      "terms": {
        "field": "status",
        "size": 10,
        "order": { "_count": "desc" }
      }
    }
  }
}

// Nested sub-aggregation
{
  "size": 0,
  "aggs": {
    "by_category": {
      "terms": { "field": "category.keyword", "size": 20 },
      "aggs": {
        "avg_price": { "avg": { "field": "price" } },
        "total_sales": { "sum": { "field": "amount" } }
      }
    }
  }
}

// multi_terms: group by multiple fields (ES 7.12+)
{
  "aggs": {
    "by_cat_status": {
      "multi_terms": {
        "terms": [{ "field": "category" }, { "field": "status" }]
      }
    }
  }
}

Date Histogram

// date_histogram: bucket by time interval
{
  "size": 0,
  "aggs": {
    "orders_over_time": {
      "date_histogram": {
        "field":            "created_at",
        "calendar_interval": "month",
        "format":           "yyyy-MM",
        "min_doc_count":    0,
        "extended_bounds": {
          "min": "2024-01-01",
          "max": "2024-12-31"
        }
      },
      "aggs": {
        "revenue": { "sum": { "field": "total" } },
        "unique_users": { "cardinality": { "field": "user_id" } }
      }
    }
  }
}

// fixed_interval: precise intervals
"fixed_interval": "7d"   // 7 days
"fixed_interval": "1h"   // 1 hour

Range & Histogram

// range: custom bucket boundaries
{
  "aggs": {
    "price_ranges": {
      "range": {
        "field": "price",
        "ranges": [
          { "key": "cheap",  "to": 50 },
          { "key": "mid",    "from": 50, "to": 200 },
          { "key": "premium","from": 200 }
        ]
      }
    }
  }
}

// histogram: fixed-width buckets
{
  "aggs": {
    "price_histogram": {
      "histogram": {
        "field":    "price",
        "interval": 50,
        "min_doc_count": 0
      }
    }
  }
}

Metric Aggregations

// Single-value metrics
{ "aggs": { "total":    { "sum":   { "field": "amount" } } } }
{ "aggs": { "average":  { "avg":   { "field": "price"  } } } }
{ "aggs": { "highest":  { "max":   { "field": "score"  } } } }
{ "aggs": { "lowest":   { "min":   { "field": "score"  } } } }
{ "aggs": { "n_docs":   { "value_count": { "field": "id" } } } }
{ "aggs": { "n_unique":  { "cardinality": { "field": "user_id" } } } }

// stats: min, max, sum, count, avg in one shot
{ "aggs": { "price_stats": { "stats": { "field": "price" } } } }

// extended_stats: adds std_deviation, variance, sum_of_squares
{ "aggs": { "ex": { "extended_stats": { "field": "price" } } } }

// percentiles
{
  "aggs": {
    "latency_pct": {
      "percentiles": {
        "field": "response_ms",
        "percents": [50, 90, 95, 99]
      }
    }
  }
}

// top_hits: return example documents per bucket
{
  "aggs": {
    "by_category": {
      "terms": { "field": "category" },
      "aggs": {
        "top_docs": {
          "top_hits": { "size": 3, "_source": ["title","price"] }
        }
      }
    }
  }
}

Pipeline Aggregations

// cumulative_sum: running total over buckets
{
  "aggs": {
    "monthly": {
      "date_histogram": { "field": "date", "calendar_interval": "month" },
      "aggs": {
        "revenue": { "sum": { "field": "amount" } },
        "cumulative_revenue": {
          "cumulative_sum": { "buckets_path": "revenue" }
        }
      }
    }
  }
}

// derivative: change between adjacent buckets
"daily_change": { "derivative": { "buckets_path": "revenue" } }

// moving_avg / moving_fn: smoothed values
"smoothed": {
  "moving_fn": {
    "buckets_path": "revenue",
    "window": 7,
    "script": "MovingFunctions.unweightedAvg(values)"
  }
}

// bucket_sort: sort/paginate buckets
"sort_buckets": {
  "bucket_sort": {
    "sort": [{ "revenue": { "order": "desc" } }],
    "size": 5
  }
}