Sum aggregation #

A single-value metrics aggregation that sums up numeric values that are extracted from the aggregated documents. It turns “how much in total” into one number — revenue, bytes, durations, counts of units — without shipping the matching documents anywhere.

How it works #

The engine walks the matching documents once, adding each value to a running total. 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. With missing set, every such document adds the default to the total — on the column-store fast path (the production executor) this is computed as missing × absent_count per segment, where the column’s sum_f64 batch reducer supplies the sum of the present values in the same pass.

The sum is exact, and stays exact across shards: per-shard totals combine by plain addition, so distributed and single-node requests return the same number.

sum never returns null — when nothing contributed, the result is 0.0 (an empty bucket is an empty total, not an unknown one).

Examples #

Summing the price of every hat — the SQL pill beside the Run button is the same question with a WHERE scoping the sum:

POST /sales/_search
{
  "query": {
    "term": {
      "field": "type",
      "value": "hat"
    }
  },
  "aggs": {
    "hat_prices": {
      "sum": {
        "field": "price"
      }
    }
  }
}

Resulting in:

{
  ...
  "aggregations": {
    "hat_prices": {
      "value": 900.0
    }
  }
}

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

Use cases #

• Revenue reporting. sales.sum(amount) = 6750.0 across the 120 teaching sales — total turnover in one request, no matter the match count.
• Per-group totals. Nested under terms on type, sum(price) returns t-shirt: 900 / hat: 900 / mug: 900 / sticker: 600 — the ranking a leaderboard needs.
• Stock on hand. products.sum(stock) = 1445 units across the 30 catalog products, and the same aggregation inside a filter drives low-stock alerts.
• Cross-checking counts. Sum a field that is always 1 to verify a doc_count you distrust; or divide a sum by a value_count for an average computed client-side.
• Billing-style rollups. Because shard totals combine by addition, a sum over a date range is safe to fan out and merge — no double counting, no estimates.

Parameters for sum #

• 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; each such document adds it to the total.

Related #

• avg — the total divided by how many contributed
• stats — sum plus count/min/max/avg in one request
• value_count — how many values went into the sum
• sum_bucket — sum over another aggregation’s bucket values