Aggregations Reference

Full reference for Elasticsearch aggregation types. All examples are JSON bodies for POST /<index>/_search?size=0.

Table of Contents

• Metric Aggregations
• Bucket Aggregations
• Pipeline Aggregations
• Patterns

Metric Aggregations

Basic metrics

{
  "aggs": {
    "avg_response":  { "avg":  { "field": "response_time" } },
    "max_response":  { "max":  { "field": "response_time" } },
    "min_response":  { "min":  { "field": "response_time" } },
    "sum_bytes":     { "sum":  { "field": "bytes" } },
    "total_docs":    { "value_count": { "field": "_id" } }
  }
}

stats / extended_stats

All basic metrics in one shot:

{ "aggs": { "response_stats": { "stats": { "field": "response_time" } } } }
{ "aggs": { "response_ext": { "extended_stats": { "field": "response_time" } } } }

extended_stats adds: std_deviation, variance, std_deviation_bounds

cardinality (approximate distinct count)

{ "aggs": { "unique_users": { "cardinality": { "field": "user_id" } } } }

percentiles / percentile_ranks

{ "aggs": { "latency_pcts": { "percentiles": { "field": "response_time", "percents": [50, 90, 95, 99] } } } }
{ "aggs": { "under_200ms": { "percentile_ranks": { "field": "response_time", "values": [200, 500, 1000] } } } }

top_hits (get sample documents per bucket)

{
  "aggs": {
    "by_service": {
      "terms": { "field": "service.name" },
      "aggs": {
        "latest": {
          "top_hits": { "size": 3, "sort": [ { "@timestamp": "desc" } ], "_source": ["message", "level"] }
        }
      }
    }
  }
}

weighted_avg

{
  "aggs": {
    "weighted_score": {
      "weighted_avg": {
        "value": { "field": "score" },
        "weight": { "field": "importance" }
      }
    }
  }
}

Bucket Aggregations

terms (top N values)

{
  "aggs": {
    "top_services": {
      "terms": { "field": "service.name", "size": 20, "order": { "_count": "desc" } }
    }
  }
}

Use "missing": "unknown" to include docs where field is absent.

date_histogram

{
  "aggs": {
    "over_time": {
      "date_histogram": {
        "field": "@timestamp",
        "fixed_interval": "1h",
        "min_doc_count": 0,
        "extended_bounds": { "min": "now-24h", "max": "now" }
      }
    }
  }
}

Intervals: fixed_interval (e.g., 30s, 5m, 1h, 1d) or calendar_interval (minute, hour, day, week, month, year).

histogram (numeric buckets)

{ "aggs": { "response_dist": { "histogram": { "field": "response_time", "interval": 100 } } } }

range / date_range

{
  "aggs": {
    "latency_buckets": {
      "range": {
        "field": "response_time",
        "ranges": [
          { "key": "fast",   "to": 100 },
          { "key": "medium", "from": 100, "to": 500 },
          { "key": "slow",   "from": 500 }
        ]
      }
    }
  }
}

filters (named buckets from queries)

{
  "aggs": {
    "status": {
      "filters": {
        "filters": {
          "errors": { "term": { "level": "error" } },
          "warnings": { "term": { "level": "warn" } },
          "info": { "term": { "level": "info" } }
        }
      }
    }
  }
}

significant_terms (unusual terms vs background)

{
  "query": { "term": { "level": "error" } },
  "aggs": {
    "unusual_words": { "significant_terms": { "field": "message.keyword", "size": 10 } }
  }
}

composite (paginated aggregation — for large cardinality)

{
  "aggs": {
    "paginated": {
      "composite": {
        "size": 100,
        "sources": [
          { "service": { "terms": { "field": "service.name" } } },
          { "level":   { "terms": { "field": "level" } } }
        ]
      }
    }
  }
}

Paginate by passing "after": { "service": "last-value", "level": "last-value" } from previous response.

multi_terms (group by multiple fields)

{
  "aggs": {
    "service_level": {
      "multi_terms": {
        "terms": [
          { "field": "service.name" },
          { "field": "level" }
        ],
        "size": 50
      }
    }
  }
}

nested (aggregate on nested objects)

{
  "aggs": {
    "comments": {
      "nested": { "path": "comments" },
      "aggs": {
        "top_authors": { "terms": { "field": "comments.author.keyword" } }
      }
    }
  }
}

sampler / diversified_sampler

Limit analysis to top N scoring docs (performance optimization):

{
  "aggs": {
    "sample": {
      "sampler": { "shard_size": 200 },
      "aggs": {
        "keywords": { "significant_terms": { "field": "message.keyword" } }
      }
    }
  }
}

Pipeline Aggregations

Operate on output of other aggregations.

moving_avg / moving_fn

{
  "aggs": {
    "over_time": {
      "date_histogram": { "field": "@timestamp", "fixed_interval": "1h" },
      "aggs": {
        "avg_response": { "avg": { "field": "response_time" } },
        "smoothed": {
          "moving_fn": { "buckets_path": "avg_response", "window": 5, "script": "MovingFunctions.unweightedAvg(values)" }
        }
      }
    }
  }
}

derivative (rate of change)

{
  "aggs": {
    "over_time": {
      "date_histogram": { "field": "@timestamp", "fixed_interval": "1h" },
      "aggs": {
        "total": { "sum": { "field": "count" } },
        "rate_of_change": { "derivative": { "buckets_path": "total" } }
      }
    }
  }
}

cumulative_sum

{
  "aggs": {
    "over_time": {
      "date_histogram": { "field": "@timestamp", "fixed_interval": "1d" },
      "aggs": {
        "daily_count": { "value_count": { "field": "_id" } },
        "running_total": { "cumulative_sum": { "buckets_path": "daily_count" } }
      }
    }
  }
}

bucket_script (compute across sibling metrics)

{
  "aggs": {
    "by_service": {
      "terms": { "field": "service.name" },
      "aggs": {
        "errors":  { "filter": { "term": { "level": "error" } } },
        "total":   { "value_count": { "field": "_id" } },
        "error_rate": {
          "bucket_script": {
            "buckets_path": { "err": "errors._count", "tot": "total" },
            "script": "params.err / params.tot * 100"
          }
        }
      }
    }
  }
}

bucket_sort (sort/limit aggregation buckets)

{
  "aggs": {
    "by_service": {
      "terms": { "field": "service.name", "size": 100 },
      "aggs": {
        "avg_latency": { "avg": { "field": "response_time" } },
        "sort_by_latency": {
          "bucket_sort": { "sort": [ { "avg_latency": { "order": "desc" } } ], "size": 10 }
        }
      }
    }
  }
}

bucket_selector (filter buckets by condition)

{
  "aggs": {
    "by_service": {
      "terms": { "field": "service.name" },
      "aggs": {
        "avg_latency": { "avg": { "field": "response_time" } },
        "slow_only": {
          "bucket_selector": {
            "buckets_path": { "lat": "avg_latency" },
            "script": "params.lat > 500"
          }
        }
      }
    }
  }
}

Patterns

Error rate over time (SRE dashboard)

{
  "size": 0,
  "query": { "range": { "@timestamp": { "gte": "now-24h" } } },
  "aggs": {
    "over_time": {
      "date_histogram": { "field": "@timestamp", "fixed_interval": "15m" },
      "aggs": {
        "total":  { "value_count": { "field": "_id" } },
        "errors": { "filter": { "term": { "level": "error" } } },
        "error_rate": {
          "bucket_script": {
            "buckets_path": { "err": "errors._count", "tot": "total" },
            "script": "params.tot > 0 ? (params.err / params.tot * 100) : 0"
          }
        }
      }
    }
  }
}

Top N with details (leaderboard)

{
  "size": 0,
  "aggs": {
    "top_endpoints": {
      "terms": { "field": "url.path.keyword", "size": 10 },
      "aggs": {
        "avg_latency": { "avg": { "field": "response_time" } },
        "p99_latency": { "percentiles": { "field": "response_time", "percents": [99] } },
        "error_count": { "filter": { "range": { "http.response.status_code": { "gte": 500 } } } }
      }
    }
  }
}