# 扩展统计聚合( Extended Stats Aggregation)

多值度量聚合计算从汇总文档中提取的数值的统计数据。这些值可以从文档中的特定数值字段中提取，也可以由提供的脚本生成。

扩展统计聚合是统计聚合（[`stats`](https://www.elastic.co/guide/en/elasticsearch/reference/5.3/search-aggregations-metrics-stats-aggregation.html) aggregation）的扩展版本，其中额外添加如`sum_of_squares`, `variance`, `std_deviation` and `std_deviation_bounds。`

假设数据由学生的考试成绩（0到100）组成：

```
{ 
    "aggs" : { 
        "grades_stats" : { 
            "extended_stats" : { 
                "field" : "grade" 
            } 
        } 
    } 
}
```

上述聚合计算所有文档的分数统计信息。聚合类型为extended\_stats，设置文档的数字字段为需要统计的字段为grade，执行上面的语句将返回如下：

```
{
    ...

    "aggregations": {
        "grade_stats": {
           "count": 9,
           "min": 72,
           "max": 99,
           "avg": 86,
           "sum": 774,
           "sum_of_squares": 67028,
           "variance": 51.55555555555556,
           "std_deviation": 7.180219742846005,
           "std_deviation_bounds": {
            "upper": 100.36043948569201,
            "lower": 71.63956051430799
           }
        }
    }
}
```

聚合的名称（上面语句中的grades\_stats）作为key，通过该key可以从返回的结果中检索出聚集的结果。

## Standard Deviation Bounds

默认情况下，扩展统计度量将返回一个对象称为std\_deviation\_bounds，它提供了平均值加/减两个标准差的区间。这可以成为一个用来方式来可视化数据的方差。如果你想要一个不同的边界，例如三个标准偏差，你可以在请求中设置：

```
{
    "aggs" : {
        "grades_stats" : {
            "extended_stats" : {
                "field" : "grade",
                "sigma" : 3  # 1
            }
        }
    }
}
```

| 1 | 控制应显示多少标准偏差+/-平均值。 |
| - | ------------------ |

sigma可以是任何非负double类型数字，这意味着你可以要求非整数值，如1.5。值为0也是有效的，但只会返回上下限的平均值。

提示：默认情况下显示标准偏差和其边界，但它们并不总是适用于所有的数据集。您的数据必须是正常分布的度量才有意义。标准偏差背后的统计数据假设为正常分布的数据，因此如果数据偏斜向左或向右，返回的值将是误导性的。

## Script

使用下面的脚本计算成绩的统计信息：

```
{
    ...,

    "aggs" : {
        "grades_stats" : {
            "extended_stats" : {
                "script" : {
                    "inline" : "doc['grade'].value",
                    "lang" : "painless"
                 }
             }
         }
    }
}
```

用下面的语法来使用脚本文件：

```
{
    ...,

    "aggs" : {
        "grades_stats" : {
            "extended_stats" : {
                "script" : {
                    "file": "my_script",
                    "params": {
                        "field": "grade"
                    }
                }
            }
        }
    }
}
```

> ```
> 提示：可以使用id参数代替file参数来使用index的脚本。
> ```

## Value Script

当考试的难度是高于学生的水平，需要校正学生的成绩，我们可以使用value script获得新的统计：

```
{
    "aggs" : {
        ...

        "aggs" : {
            "grades_stats" : {
                "extended_stats" : {
                    "field" : "grade",
                    "script" : {
                        "lang" : "painless",
                        "inline": "_value * params.correction",
                        "params" : {
                            "correction" : 1.2
                        }
                    }
                }
            }
        }
    }
}
```

## Missing Value

missing参数定义了如何处理缺少值的文档。 默认情况下如果没有指定的字段，这种文档将被忽略，但也可以认为它们具有指定的值：

```
{
    "aggs" : {
        "grades_stats" : {
            "extended_stats" : {
                "field" : "grade",
                "missing": 0  # 1
            }
        }
    }
}
```

| 1 | 文档中如果没有grade这个字段，则认为该字段的值是0。 |
| - | ---------------------------- |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://xiaoxiami.gitbook.io/elasticsearch/ji-chu/36aggregationsju-he-fen-679029/liang-du-ju-540828-metric-aggregations/kuo-zhan-tong-ji-ju-540828-extended-stats-aggregation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.