Stats aggregation #

A multi-value metrics aggregation that computes basic statistics (min, max, sum, count, avg) over numeric values extracted from the aggregated documents. It is avg, min, max and sum folded into one request — the five numbers most dashboards put side by side, for the price of one column scan.

How it works #

The engine walks the matching documents once, maintaining a running count, sum, minimum and maximum; avg is derived at the end as sum / count. Everything is exact — no sampling, no sketches. Values are coerced to doubles as they are read: integers, floats and booleans (true = 1, false = 0) contribute, non-numeric values such as keyword strings do not.

Documents that lack the field are skipped by default, lowering the count. With missing set, every such document contributes the default to the sum, the extremes and the count, exactly as if the field had carried it.

On the column-store fast path (the production executor) the five numbers come out of one fused pass per segment (stats_f64, a full-segment SIMD scan when eligible) instead of three separate sum/min/max walks. The result carries count and sum alongside avg, which is what makes merging exact: distributed requests combine per-shard count/sum by addition, fold min/max pairwise, and recompute avg from the merged totals — identical to a single-node answer.

When no document contributed a value, count is 0, sum is 0.0, and min, max and avg are null.

Examples #

The five numbers as one statement on the SQL side — COUNT(*), MIN, MAX, AVG, SUM side by side:

POST /sales/_search
{
  "aggs": {
    "prices_stats": {
      "stats": {
        "field": "price"
      }
    }
  }
}

Response:

{
  ...
  "aggregations": {
    "prices_stats": {
      "count": 120,
      "min": 15.0,
      "max": 60.0,
      "avg": 27.5,
      "sum": 3300.0
    }
  }
}

Use cases #

• One-request KPI cards. The five numbers every summary header shows — over the teaching sales: count 120, min 15.0, max 60.0, avg 27.5, sum 3300.0 — in a single aggregation instead of five.
• Per-group profiles. Nested under terms on type, each bucket gets its own five numbers — hats: count 30, min 30, max 30, avg 30, sum 900 — the shape of each product line at a glance.
• Spread intuition before percentiles. min and max against avg show how wide the distribution runs; when the mean hugs an extreme, reach for percentiles or a histogram.
• Data sanity on ingest. A count below the match count means missing values; a min or max outside the legal range flags bad writes before anything downstream notices.
• Cheap composite metrics. Divide sum by count client-side, or feed both into a bucket_script to build ratios per bucket without a second pass.

Parameters for stats #

• field
  (Required, string) Field you wish to aggregate.
• missing
  (Optional, value) Value used for documents missing the field.

extended_stats takes the same parameters and additionally returns variance, standard deviation and related statistics.

Related #

• extended_stats — adds sum-of-squares, variance and standard deviation
• avg / sum / min / max — the individual numbers when you only need one
• stats_bucket — the same statistics over another aggregation’s buckets