Avg aggregation #

A single-value metrics aggregation that computes the average of numeric values that are extracted from the aggregated documents. It summarizes “what does a typical matching document look like on this field” into one number — the question SQL spells AVG(price) — without fetching a single document.

How it works #

The engine walks the matching documents once, keeping a running sum and count; the result is sum / count. Nothing is estimated: the average is exact. 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 both the sum and the count, exactly as if the field had carried that value. A non-numeric missing string cannot be coerced and is dropped.

On the column-store fast path (the production executor) each segment’s column is decoded once and reduced in a single batch (sum_f64) instead of dispatching per document; segments accumulate into one running sum/count. That pair also makes distributed requests exact: in partial mode avg is rewritten to stats on the shards, so count and sum combine losslessly across shards and the coordinator projects the merged pair back to {"value": …} when finalizing.

When no document contributed a value, the result is null.

Examples #

The average price over every sale — flip to SQL (beside the Run button) to ask the same question as one AVG(price) statement:

POST /sales/_search
{
  "aggs": {
    "avg_price": {
      "avg": {
        "field": "price"
      }
    }
  }
}

The aggregation type is avg and the field setting defines the numeric field of the documents the average will be computed on. Over the teaching dataset’s 120 sales this returns:

{
  ...
  "aggregations": {
    "avg_price": {
      "value": 27.5
    }
  }
}

The name of the aggregation (avg_price above) also serves as the key by which the aggregation result can be retrieved from the returned response.

Use cases #

• Sanity-check a filter. sales.avg(price) is 27.5; the same aggregation inside a term filter on type = "hat" returns 30.0. One number tells you the filter selects what you think it selects.
• Compare groups. Nest avg under terms: avg price per type comes out t-shirt: 15 / hat: 30 / mug: 45 / sticker: 60 — the teaching dataset’s deliberate price ladder.
• Dashboard KPIs. Average order size (sales.avg(amount) = 56.25) or catalogue price point (products.avg(price) ≈ 15.43 over 30 products) refresh in one request.
• Average of a magnitude-bearing field. A 3-unit sale counts as much as a 1-unit sale here; when each document carries a qty, switch to weighted_avg — price weighted by quantity sold is 28.125, a half point above the plain 27.5.

Parameters for avg #

• field
  (Required, string) Field you wish to aggregate.
• script
  (Optional, object) Script evaluated per document as the value source — mutually exclusive with field.
• missing
  (Optional, number) Value used for documents missing the field; they contribute it to both the sum and the count.

Related #

• stats — avg plus count/min/max/sum in one request
• weighted_avg — weight each document before averaging
• sum — the total behind the average
• terms — avg per group with a sub-aggregation