OpenSearch/docs/reference/search/aggregations/metrics/extendedstats-aggregation.asciidoc

[[search-aggregations-metrics-extendedstats-aggregation]]
=== Extended Stats

A `multi-value` metrics aggregation that computes stats over numeric values extracted from the aggregated documents. These values can be extracted either from specific numeric fields in the documents, or be generated by a provided script.

The `extended_stats` aggregations is an extended version of the <<search-aggregations-metrics-stats-aggregation,`stats`>> aggregation, where additional metrics are added such as `sum_of_squares`, `variance` and `std_deviation`.

Assuming the data consists of documents representing exams grades (between 0 and 100) of students

[source,js]
--------------------------------------------------
{
    "aggs" : {
        "grades_stats" : { "extended_stats" : { "field" : "grade" } }
    }
}
--------------------------------------------------

The above aggregation computes the grades statistics over all documents. The aggregation type is `extended_stats` and the `field` setting defines the numeric field of the documents the stats will be computed on. The above will return the following:


[source,js]
--------------------------------------------------
{
    ...

    "aggregations": {
        "grades_stats": {
            "count": 6,
            "min": 72,
            "max": 117.6,
            "avg": 94.2,
            "sum": 565.2,
            "sum_of_squares": 54551.51999999999,
            "variance": 218.2799999999976,
            "std_deviation": 14.774302013969987
        }
    }
}
--------------------------------------------------

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

==== Script

Computing the grades stats based on a script:

[source,js]
--------------------------------------------------
{
    ...,

    "aggs" : {
        "grades_stats" : { "extended_stats" : { "script" : "doc['grade'].value" } }
    }
}
--------------------------------------------------

===== Value Script

It turned out that the exam was way above the level of the students and a grade correction needs to be applied. We can use value script to get the new stats:

[source,js]
--------------------------------------------------
{
    "aggs" : {
        ...

        "aggs" : {
            "grades_stats" : {
                "extended_stats" : { 
                    "field" : "grade",
                    "script" : "_value * correction",
                    "params" : {
                        "correction" : 1.2
                    }
                }
            }
        }
    }
}
--------------------------------------------------