You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The `stats`metric is a multi-value metric aggregation that returns all basic metrics such as `min`, `max`, `sum`, `avg`, and `value_count` in one aggregation query.
12
+
The `stats`aggregation is a multi-value metric aggregation that computes a summary of numeric data. This aggregation is useful for quickly understanding the distribution of numeric fields. It can operate directly on a field, apply a script to derive the values, or handle documents with missing fields. The `stats` aggregation returns five values:
13
13
14
-
The following example returns the basic stats for the `taxful_total_price` field:
14
+
*`count`: The number of values collected
15
+
*`min`: The lowest value
16
+
*`max`: The highest value
17
+
*`sum`: The total of all values
18
+
*`avg`: The average of the values (sum divided by count)
19
+
20
+
## Parameters
21
+
22
+
The `stats` aggregation takes the following optional parameters.
|`field`| String | The field to aggregate on. Must be a numeric field. |
27
+
|`script`| Object | The script used to calculate custom values for aggregation. Can be used instead of or with `field`. |
28
+
| `missing` | Number | The default value used for documents missing the target field.
29
+
30
+
## Example
31
+
32
+
The following example computes a `stats` aggregation for electricity usage.
33
+
34
+
Create an index named `power_usage` and add documents containing the number of kilowatt-hours (kWh) consumed during a given hour:
15
35
16
36
```json
17
-
GET opensearch_dashboards_sample_data_ecommerce/_search
37
+
PUT /power_usage/_bulk?refresh=true
38
+
{"index": {}}
39
+
{"device_id": "A1", "kwh": 1.2}
40
+
{"index": {}}
41
+
{"device_id": "A2", "kwh": 0.7}
42
+
{"index": {}}
43
+
{"device_id": "A3", "kwh": 1.5}
44
+
```
45
+
{% include copy-curl.html %}
46
+
47
+
To compute statistics on the `kwh` field across all documents, use a `stats` aggregation named `consumption_stats` over the `kwh` field. Setting `size` to `0` specifies that document hits should not be returned:
48
+
49
+
```json
50
+
GET /power_usage/_search
18
51
{
19
52
"size": 0,
20
53
"aggs": {
21
-
"stats_taxful_total_price": {
54
+
"consumption_stats": {
22
55
"stats": {
23
-
"field": "taxful_total_price"
56
+
"field": "kwh"
24
57
}
25
58
}
26
59
}
27
60
}
28
61
```
29
62
{% include copy-curl.html %}
30
63
31
-
#### Example response
64
+
The response includes `count`, `min`, `max`, `avg`, and `sum` values for the three documents in the index:
32
65
33
66
```json
34
-
...
35
-
"aggregations" : {
36
-
"stats_taxful_total_price" : {
37
-
"count" : 4675,
38
-
"min" : 6.98828125,
39
-
"max" : 2250.0,
40
-
"avg" : 75.05542864304813,
41
-
"sum" : 350884.12890625
67
+
{
68
+
...
69
+
"hits": {
70
+
"total": {
71
+
"value": 3,
72
+
"relation": "eq"
73
+
},
74
+
"max_score": null,
75
+
"hits": []
76
+
},
77
+
"aggregations": {
78
+
"consumption_stats": {
79
+
"count": 3,
80
+
"min": 0.699999988079071,
81
+
"max": 1.5,
82
+
"avg": 1.1333333452542622,
83
+
"sum": 3.400000035762787
84
+
}
42
85
}
43
-
}
44
86
}
45
-
```
87
+
```
88
+
89
+
### Running a stats aggregation per bucket
90
+
91
+
You can compute separate statistics for each device by nesting a `stats` aggregation inside a `terms` aggregation in the `device_id` field. The `terms` aggregation groups documents into buckets based on unique `device_id` values, and the `stats` aggregation computes summary statistics within each bucket:
92
+
93
+
```json
94
+
GET /power_usage/_search
95
+
{
96
+
"size": 0,
97
+
"aggs": {
98
+
"per_device": {
99
+
"terms": {
100
+
"field": "device_id.keyword"
101
+
},
102
+
"aggs": {
103
+
"device_usage_stats": {
104
+
"stats": {
105
+
"field": "kwh"
106
+
}
107
+
}
108
+
}
109
+
}
110
+
}
111
+
}
112
+
```
113
+
{% include copy-curl.html %}
114
+
115
+
The response returns one bucket per `device_id`, with computed `count`, `min`, `max`, `avg`, and `sum` fields within each bucket:
116
+
117
+
```json
118
+
{
119
+
...
120
+
"hits": {
121
+
"total": {
122
+
"value": 3,
123
+
"relation": "eq"
124
+
},
125
+
"max_score": null,
126
+
"hits": []
127
+
},
128
+
"aggregations": {
129
+
"per_device": {
130
+
"doc_count_error_upper_bound": 0,
131
+
"sum_other_doc_count": 0,
132
+
"buckets": [
133
+
{
134
+
"key": "A1",
135
+
"doc_count": 1,
136
+
"device_usage_stats": {
137
+
"count": 1,
138
+
"min": 1.2000000476837158,
139
+
"max": 1.2000000476837158,
140
+
"avg": 1.2000000476837158,
141
+
"sum": 1.2000000476837158
142
+
}
143
+
},
144
+
{
145
+
"key": "A2",
146
+
"doc_count": 1,
147
+
"device_usage_stats": {
148
+
"count": 1,
149
+
"min": 0.699999988079071,
150
+
"max": 0.699999988079071,
151
+
"avg": 0.699999988079071,
152
+
"sum": 0.699999988079071
153
+
}
154
+
},
155
+
{
156
+
"key": "A3",
157
+
"doc_count": 1,
158
+
"device_usage_stats": {
159
+
"count": 1,
160
+
"min": 1.5,
161
+
"max": 1.5,
162
+
"avg": 1.5,
163
+
"sum": 1.5
164
+
}
165
+
}
166
+
]
167
+
}
168
+
}
169
+
}
170
+
```
171
+
172
+
This allows you to compare usage statistics across devices with a single query.
173
+
174
+
### Using a script to compute derived values
175
+
176
+
You can also use a script to compute the values used in the `stats` aggregation. This is useful when the metric is derived from document fields or requires transformation.
177
+
178
+
For example, to convert kilowatt-hours (kWh) to watt-hours (Wh) before running the `stats` aggregation, because `1 kWh` equals `1,000 Wh`, you can use a script that multiplies each value by `1,000`. The following script `doc['kwh'].value * 1000` is used to derive the input value for each document:
179
+
180
+
```json
181
+
GET /power_usage/_search
182
+
{
183
+
"size": 0,
184
+
"aggs": {
185
+
"usage_wh_stats": {
186
+
"stats": {
187
+
"script": {
188
+
"source": "doc['kwh'].value * 1000"
189
+
}
190
+
}
191
+
}
192
+
}
193
+
}
194
+
```
195
+
{% include copy-curl.html %}
196
+
197
+
The `stats` aggregation returned in the response reflects values of `1200`, `700`, and `1500` Wh:
198
+
199
+
```json
200
+
{
201
+
...
202
+
"hits": {
203
+
"total": {
204
+
"value": 3,
205
+
"relation": "eq"
206
+
},
207
+
"max_score": null,
208
+
"hits": []
209
+
},
210
+
"aggregations": {
211
+
"usage_wh_stats": {
212
+
"count": 3,
213
+
"min": 699.999988079071,
214
+
"max": 1500,
215
+
"avg": 1133.3333452542622,
216
+
"sum": 3400.000035762787
217
+
}
218
+
}
219
+
}
220
+
```
221
+
222
+
### Using a value script with a field
223
+
224
+
When combining a field with a transformation, you can specify both `field` and `script`. This allows using the `_value` variable to reference the field's value within the script.
225
+
226
+
The following example increases each energy reading by 5% before computing the `stats` aggregation:
227
+
228
+
```json
229
+
GET /power_usage/_search
230
+
{
231
+
"size": 0,
232
+
"aggs": {
233
+
"adjusted_usage": {
234
+
"stats": {
235
+
"field": "kwh",
236
+
"script": {
237
+
"source": "_value * 1.05"
238
+
}
239
+
}
240
+
}
241
+
}
242
+
}
243
+
```
244
+
{% include copy-curl.html %}
245
+
246
+
### Missing values
247
+
248
+
If some documents do not contain the target field, they are excluded by default from the aggregation. To include them using a default value, you can specify the `missing` parameter.
249
+
250
+
The following request treats missing `kwh` values as `0.0`:
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments