Metric Aggregations

Analogy categoryAnalogies

What Are Metric Aggregations?

Metric aggregations compute numeric summaries over the set of documents matched by a query, and they come in two flavors: single-value aggregations like avg, sum, min, max, and value_count that return one number, and multi-value aggregations like stats, extended_stats, percentiles, and cardinality that return several related numbers in one response. Elasticsearch evaluates them over doc_values rather than scanning source documents, which keeps them fast even across millions of hits.

🏏

Cricket analogy: It's like asking for a single stat line after a match, MS Dhoni's strike rate in a chase, versus a full scorecard breakdown of boundaries, dot balls, and partnerships in one summary.

Single-Value Metric Aggregations

The most common single-value aggregations are avg, sum, min, max, and value_count, each of which takes a numeric or date field and produces exactly one number per bucket, or one number for the whole query if used at the top level. These read directly from a field's doc_values, so they require the field to be mapped as a numeric, date, or keyword type rather than analyzed text, since analyzed text has no stable per-document value to aggregate over.

🏏

Cricket analogy: It's like computing Virat Kohli's average across a series, one clean number, versus per-ball data, since you need a defined numeric value per innings, not commentary text, to average anything.

json

GET /orders/_search
{
  "size": 0,
  "query": {
    "range": { "order_date": { "gte": "2026-01-01" } }
  },
  "aggs": {
    "total_revenue":  { "sum": { "field": "total_price" } },
    "average_order":  { "avg": { "field": "total_price" } },
    "highest_order":  { "max": { "field": "total_price" } },
    "orders_placed":  { "value_count": { "field": "order_id" } }
  }
}

Multi-Value and Approximate Aggregations

The stats aggregation returns count, min, max, avg, and sum together in a single pass, while extended_stats adds variance, standard deviation, and standard deviation bounds. Cardinality estimates the number of distinct values using the HyperLogLog++ algorithm rather than exact counting, and percentiles estimates distribution points like the 95th percentile using the TDigest algorithm, both trading a small amount of accuracy for bounded memory usage on very large datasets.

🏏

Cricket analogy: It's like getting a full stats aggregation, average, best, and worst score, from one training session, while estimating how many distinct opponents a player has faced this season without listing each one.

The cardinality aggregation's precision_threshold parameter (default 3000) controls the trade-off between memory usage and accuracy: below the threshold, distinct counts are close to exact, while above it, the HyperLogLog++ algorithm keeps memory bounded but the error rate grows slightly. Raising precision_threshold to, say, 40000 costs roughly 40KB of memory per aggregation but tightens accuracy for high-cardinality fields.

Combining Metrics with Queries and Filters

Metric aggregations execute within the query context, meaning they only summarize documents that matched the top-level query, and they're commonly wrapped in a filter aggregation to compute metrics over a specific slice without duplicating the whole query. This lets you compute, for example, average order value for orders from a single region within one request, and metric aggregations are also the leaves that bucket aggregations, covered separately, attach to for per-group summaries.

🏏

Cricket analogy: It's like computing strike rate only for a batter's innings against pace bowling, filtering the ball-by-ball data first, then running the average, the way analysts split Rohit Sharma's stats by bowling type.

Metric aggregations cannot run directly on text fields analyzed for full-text search, because analyzed text has no single stable value per document to sum or average. Map the field as keyword, numeric, or date if you need to aggregate on it, or use a multi-field mapping so the same source field is indexed both as analyzed text for search and as keyword for aggregation.

Metric aggregations return numeric summaries: single-value (avg, sum, min, max, value_count) or multi-value (stats, extended_stats, percentiles, cardinality).
They read from doc_values, a columnar on-disk structure, not from the inverted index or _source, which makes them fast at scale.
cardinality uses the HyperLogLog++ algorithm for approximate distinct counts, controlled by the precision_threshold parameter.
percentiles uses the TDigest algorithm to estimate distribution points like p95 or p99 without storing every value.
Metric aggregations only summarize documents that match the surrounding query context, and can be scoped further with a filter aggregation.
Fields must be numeric, date, or keyword to be aggregated; analyzed text fields require a keyword sub-field via multi-fields.
stats and extended_stats compute several related numbers, count, min, max, avg, sum, variance, and std deviation, in a single aggregation.