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.
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.
Practice what you learned
1. Which aggregation type returns count, min, max, avg, and sum in a single response?
2. What algorithm powers the cardinality aggregation's distinct-value estimate?
3. Why can't you run an avg aggregation directly on a full-text analyzed field?
4. What does raising the precision_threshold parameter of a cardinality aggregation do?
5. Which structure do metric aggregations read from to compute values efficiently?
Was this page helpful?
You May Also Like
Bucket Aggregations
Understand how Elasticsearch's bucket aggregations group documents by terms, ranges, and dates, and how they nest with metric aggregations for multi-level breakdowns.
Nested Aggregations
Learn how the nested and reverse_nested aggregations let Elasticsearch correctly aggregate over arrays of objects mapped with the nested field type.
Aggregations vs SQL GROUP BY
Compare Elasticsearch's aggregation framework to SQL's GROUP BY and aggregate functions, covering conceptual mapping, execution model differences, and when to prefer each.
Aggregation Performance
Learn what drives aggregation performance in Elasticsearch, doc_values, shard sizing, caching, and approximate algorithms, and how to keep large aggregations fast.