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 `sum`metric is a single-value metric aggregations that returns the sum of the values of a field.
12
+
The `sum`aggregation is a single-value metric aggregation that calculates the total sum of numeric values extracted from a field across all matching documents. This aggregation is commonly used to compute totals for metrics such as revenue, quantity, or duration.
13
13
14
-
The following example calculates the total sum of the `taxful_total_price` field:
14
+
## Parameters
15
+
16
+
The `sum` aggregation takes the following parameters.
|`field`| String | The field to aggregate on. Must be a numeric field. |
21
+
|`script`| Object | The script used to calculate custom values for aggregation. Can be used instead of or with `field`. |
22
+
|`missing`| Number | The default value used for documents missing the target field. |
23
+
24
+
## Example
25
+
26
+
The following example demonstrates how to calculate the total weight of deliveries recorded in a logistics index.
27
+
28
+
Create an index:
29
+
30
+
```json
31
+
PUT /deliveries
32
+
{
33
+
"mappings": {
34
+
"properties": {
35
+
"shipment_id": { "type": "keyword" },
36
+
"weight_kg": { "type": "double" }
37
+
}
38
+
}
39
+
}
40
+
```
41
+
{% include copy-curl.html %}
42
+
43
+
Add sample documents:
44
+
45
+
```json
46
+
POST /deliveries/_bulk?refresh=true
47
+
{"index": {}}
48
+
{"shipment_id": "S001", "weight_kg": 12.5}
49
+
{"index": {}}
50
+
{"shipment_id": "S002", "weight_kg": 7.8}
51
+
{"index": {}}
52
+
{"shipment_id": "S003", "weight_kg": 15.0}
53
+
{"index": {}}
54
+
{"shipment_id": "S004", "weight_kg": 10.3}
55
+
```
56
+
{% include copy-curl.html %}
57
+
58
+
59
+
The following request computes the total weight across all documents in the `deliveries` index, omits document hits by setting `size` to `0`, and returns the total sum of `weight_kg`:
60
+
61
+
```json
62
+
GET /deliveries/_search
63
+
{
64
+
"size": 0,
65
+
"aggs": {
66
+
"total_weight": {
67
+
"sum": {
68
+
"field": "weight_kg"
69
+
}
70
+
}
71
+
}
72
+
}
73
+
```
74
+
{% include copy-curl.html %}
75
+
76
+
The response contains the value `45.6`, corresponding to the sum of `12.5` + `7.8` + `15.0` + `10.3`:
77
+
78
+
```json
79
+
{
80
+
...
81
+
"hits": {
82
+
"total": {
83
+
"value": 4,
84
+
"relation": "eq"
85
+
},
86
+
"max_score": null,
87
+
"hits": []
88
+
},
89
+
"aggregations": {
90
+
"total_weight": {
91
+
"value": 45.6
92
+
}
93
+
}
94
+
}
95
+
```
96
+
97
+
### Using a script to compute values
98
+
99
+
Instead of specifying a field directly, you can provide a script to calculate values for the aggregation. This is useful when the value must be derived or adjusted.
100
+
101
+
In the following example, each weight is converted from kilograms to grams before summing using a script:
15
102
16
103
```json
17
-
GET opensearch_dashboards_sample_data_ecommerce/_search
104
+
GET /deliveries/_search
18
105
{
19
106
"size": 0,
20
107
"aggs": {
21
-
"sum_taxful_total_price": {
108
+
"total_weight_grams": {
22
109
"sum": {
23
-
"field": "taxful_total_price"
110
+
"script": {
111
+
"source": "doc['weight_kg'].value * 1000"
112
+
}
24
113
}
25
114
}
26
115
}
27
116
}
28
117
```
29
118
{% include copy-curl.html %}
30
119
31
-
#### Example response
120
+
The response includes the `total_weight_grams` of `45600`:
32
121
33
122
```json
34
123
{
35
-
"took": 16,
36
-
"timed_out": false,
37
-
"_shards": {
38
-
"total": 1,
39
-
"successful": 1,
40
-
"skipped": 0,
41
-
"failed": 0
124
+
...
125
+
"hits": {
126
+
"total": {
127
+
"value": 4,
128
+
"relation": "eq"
129
+
},
130
+
"max_score": null,
131
+
"hits": []
42
132
},
133
+
"aggregations": {
134
+
"total_weight_grams": {
135
+
"value": 45600
136
+
}
137
+
}
138
+
}
139
+
```
140
+
141
+
### Combining a field with a value script
142
+
143
+
You can also specify both a `field` and a `script`, using the special variable `_value` to reference the field's value. This is useful when applying transformations to existing field values.
144
+
145
+
The following example increases all weights by 10% before summing:
146
+
147
+
```json
148
+
GET /deliveries/_search
149
+
{
150
+
"size": 0,
151
+
"aggs": {
152
+
"adjusted_weight": {
153
+
"sum": {
154
+
"field": "weight_kg",
155
+
"script": {
156
+
"source": "Math.round(_value * 110) / 100.0"
157
+
}
158
+
}
159
+
}
160
+
}
161
+
}
162
+
```
163
+
{% include copy-curl.html %}
164
+
165
+
The response reflects a 10% increase applied to the original total weight:
166
+
167
+
```json
168
+
{
169
+
...
43
170
"hits": {
44
171
"total": {
45
-
"value": 4675,
172
+
"value": 4,
46
173
"relation": "eq"
47
174
},
48
175
"max_score": null,
49
176
"hits": []
50
177
},
51
178
"aggregations": {
52
-
"sum_taxful_total_price": {
53
-
"value": 350884.12890625
179
+
"adjusted_weight": {
180
+
"value": 50.16
181
+
}
182
+
}
183
+
}
184
+
```
185
+
186
+
### Missing values
187
+
188
+
Documents missing the target field are ignored by default. To include them using a default value, use the `missing` parameter.
189
+
190
+
The following example assigns a default value of `0` to missing `weight_kg` fields. This ensures that the documents without this field are treated as having `weight_kg` set to `0` and included in the aggregation.
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments