OpenSearch/docs/reference/aggregations/metrics/sum-aggregation.asciidoc

[[search-aggregations-metrics-sum-aggregation]]
=== Sum Aggregation

A `single-value` metrics aggregation that sums up numeric values that are extracted from the aggregated documents.
These values can be extracted either from specific numeric or <<histogram,histogram>> fields in the documents,
or be generated by a provided script.

Assuming the data consists of documents representing sales records we can sum
the sale price of all hats with:

[source,console]
--------------------------------------------------
POST /sales/_search?size=0
{
  "query": {
    "constant_score": {
      "filter": {
        "match": { "type": "hat" }
      }
    }
  },
  "aggs": {
    "hat_prices": { "sum": { "field": "price" } }
  }
}
--------------------------------------------------
// TEST[setup:sales]

Resulting in:

[source,console-result]
--------------------------------------------------
{
  ...
  "aggregations": {
    "hat_prices": {
      "value": 450.0
    }
  }
}
--------------------------------------------------
// TESTRESPONSE[s/\.\.\./"took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits,/]

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.

==== Script

We could also use a script to fetch the sales price:

[source,console]
--------------------------------------------------
POST /sales/_search?size=0
{
  "query": {
    "constant_score": {
      "filter": {
        "match": { "type": "hat" }
      }
    }
  },
  "aggs": {
    "hat_prices": {
      "sum": {
        "script": {
          "source": "doc.price.value"
        }
      }
    }
  }
}
--------------------------------------------------
// TEST[setup:sales]

This will interpret the `script` parameter as an `inline` script with the `painless` script language and no script parameters. To use a stored script use the following syntax:

[source,console]
--------------------------------------------------
POST /sales/_search?size=0
{
  "query": {
    "constant_score": {
      "filter": {
        "match": { "type": "hat" }
      }
    }
  },
  "aggs": {
    "hat_prices": {
      "sum": {
        "script": {
          "id": "my_script",
          "params": {
            "field": "price"
          }
        }
      }
    }
  }
}
--------------------------------------------------
// TEST[setup:sales,stored_example_script]

===== Value Script

It is also possible to access the field value from the script using `_value`.
For example, this will sum the square of the prices for all hats:

[source,console]
--------------------------------------------------
POST /sales/_search?size=0
{
  "query": {
    "constant_score": {
      "filter": {
        "match": { "type": "hat" }
      }
    }
  },
  "aggs": {
    "square_hats": {
      "sum": {
        "field": "price",
        "script": {
          "source": "_value * _value"
        }
      }
    }
  }
}
--------------------------------------------------
// TEST[setup:sales]

==== Missing value

The `missing` parameter defines how documents that are missing a value should
be treated. By default documents missing the value will be ignored but it is
also possible to treat them as if they had a value. For example, this treats
all hat sales without a price as being `100`.

[source,console]
--------------------------------------------------
POST /sales/_search?size=0
{
  "query": {
    "constant_score": {
      "filter": {
        "match": { "type": "hat" }
      }
    }
  },
  "aggs": {
    "hat_prices": {
      "sum": {
        "field": "price",
        "missing": 100 <1>
      }
    }
  }
}
--------------------------------------------------
// TEST[setup:sales]

[[search-aggregations-metrics-sum-aggregation-histogram-fields]]
==== Histogram fields

When sum is computed on <<histogram,histogram fields>>, the result of the aggregation is the sum of all elements in the `values`
array multiplied by the number in the same position in the `counts` array.

For example, for the following index that stores pre-aggregated histograms with latency metrics for different networks:

[source,console]
--------------------------------------------------
PUT metrics_index/_doc/1
{
  "network.name" : "net-1",
  "latency_histo" : {
      "values" : [0.1, 0.2, 0.3, 0.4, 0.5], <1>
      "counts" : [3, 7, 23, 12, 6] <2>
   }
}

PUT metrics_index/_doc/2
{
  "network.name" : "net-2",
  "latency_histo" : {
      "values" :  [0.1, 0.2, 0.3, 0.4, 0.5], <1>
      "counts" : [8, 17, 8, 7, 6] <2>
   }
}

POST /metrics_index/_search?size=0
{
  "aggs" : {
    "total_latency" : { "sum" : { "field" : "latency_histo" } }
  }
}
--------------------------------------------------

For each histogram field the `sum` aggregation will multiply each number in the `values` array <1> multiplied by its associated count
in the `counts` array <2>. Eventually, it will add all values for all histograms and return the following result:

[source,console-result]
--------------------------------------------------
{
  ...
  "aggregations": {
    "total_latency": {
      "value": 28.8
    }
  }
}
--------------------------------------------------
// TESTRESPONSE[skip:test not setup]