From d080d228816cacff3c72f5a1de3e63a9f1e0c407 Mon Sep 17 00:00:00 2001 From: Anton Rubin Date: Mon, 14 Jul 2025 17:44:57 +0100 Subject: [PATCH 1/7] adding sum aggregations docs Signed-off-by: Anton Rubin --- _aggregations/metric/sum.md | 169 ++++++++++++++++++++++++++++++------ 1 file changed, 142 insertions(+), 27 deletions(-) diff --git a/_aggregations/metric/sum.md b/_aggregations/metric/sum.md index 2e0b32cb3dd..11fb63f0b64 100644 --- a/_aggregations/metric/sum.md +++ b/_aggregations/metric/sum.md @@ -9,18 +9,91 @@ redirect_from: # Sum aggregations -The `sum` metric is a single-value metric aggregations that returns the sum of the values of a field. +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. -The following example calculates the total sum of the `taxful_total_price` field: +## Example + +The following example demonstrates how to calculate the total weight of deliveries recorded in a logistics index. + +### Create the index + +```json +PUT /deliveries +{ + "mappings": { + "properties": { + "shipment_id": { "type": "keyword" }, + "weight_kg": { "type": "float" } + } + } +} +``` +{% include copy-curl.html %} + +### Add sample documents + +```json +POST /deliveries/_bulk?refresh=true +{"index": {}} +{"shipment_id": "S001", "weight_kg": 12.5} +{"index": {}} +{"shipment_id": "S002", "weight_kg": 7.8} +{"index": {}} +{"shipment_id": "S003", "weight_kg": 15.0} +{"index": {}} +{"shipment_id": "S004", "weight_kg": 10.3} +``` +{% include copy-curl.html %} + +### Run the sum aggregation + +The following request computes the total weight across all documents in the `deliveries` index, omits document hits and returns the total sum of `weight_kg`: + +```json +GET /deliveries/_search +{ + "size": 0, + "aggs": { + "total_weight": { + "sum": { + "field": "weight_kg" + } + } + } +} +``` +{% include copy-curl.html %} + +### Sample response + +The response contains value of `45.6` corresponding to the sum of `12.5` + `7.8` + `15.0` + `10.3`: + +```json +{ + "aggregations": { + "total_weight": { + "value": 45.6 + } + } +} +``` + +### Using a script to compute values + +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. + +In the following example, each weight is converted from kilograms to grams before summing using a script: ```json -GET opensearch_dashboards_sample_data_ecommerce/_search +GET /deliveries/_search { "size": 0, "aggs": { - "sum_taxful_total_price": { + "total_weight_grams": { "sum": { - "field": "taxful_total_price" + "script": { + "source": "doc['weight_kg'].value * 1000" + } } } } @@ -28,30 +101,72 @@ GET opensearch_dashboards_sample_data_ecommerce/_search ``` {% include copy-curl.html %} -#### Example response - -```json -{ - "took": 16, - "timed_out": false, - "_shards": { - "total": 1, - "successful": 1, - "skipped": 0, - "failed": 0 - }, - "hits": { - "total": { - "value": 4675, - "relation": "eq" - }, - "max_score": null, - "hits": [] - }, +The response includes `total_weight_grams` of 45600.0: + +```json +{ + "aggregations": { + "total_weight_grams": { + "value": 45600.0 + } + } +} +``` + +### Combining a field with a value script + +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. + +The following example increases all weights by 10% before summing: + +```json +GET /deliveries/_search +{ + "size": 0, + "aggs": { + "adjusted_weight": { + "sum": { + "field": "weight_kg", + "script": { + "source": "_value * 1.1" + } + } + } + } +} +``` +{% include copy-curl.html %} + +The response reflects a 10% increase applied to the original total weight. + +```json +{ "aggregations": { - "sum_taxful_total_price": { - "value": 350884.12890625 + "adjusted_weight": { + "value": 50.16 } } } ``` + +### Handling missing values + +Documents missing the target field are ignored by default. To include them using a default value, use the `missing` parameter. This ensures that documents without the field are treated as having zero weight and included in the aggregation. + +The following example assigns a default value of `0` for missing `weight_kg` fields: + +```json +GET /deliveries/_search +{ + "size": 0, + "aggs": { + "total_weight_with_missing": { + "sum": { + "field": "weight_kg", + "missing": 0 + } + } + } +} +``` +{% include copy-curl.html %} From be2f2dd602cd3ca2cc686325e0502450be4a1023 Mon Sep 17 00:00:00 2001 From: Anton Rubin Date: Mon, 14 Jul 2025 18:01:08 +0100 Subject: [PATCH 2/7] fixing vale errors Signed-off-by: Anton Rubin --- _aggregations/metric/sum.md | 37 +++++++++++++++++++++++++++++++------ 1 file changed, 31 insertions(+), 6 deletions(-) diff --git a/_aggregations/metric/sum.md b/_aggregations/metric/sum.md index 11fb63f0b64..866b4d28d97 100644 --- a/_aggregations/metric/sum.md +++ b/_aggregations/metric/sum.md @@ -23,7 +23,7 @@ PUT /deliveries "mappings": { "properties": { "shipment_id": { "type": "keyword" }, - "weight_kg": { "type": "float" } + "weight_kg": { "type": "double" } } } } @@ -64,12 +64,19 @@ GET /deliveries/_search ``` {% include copy-curl.html %} -### Sample response - The response contains value of `45.6` corresponding to the sum of `12.5` + `7.8` + `15.0` + `10.3`: ```json { + ... + "hits": { + "total": { + "value": 4, + "relation": "eq" + }, + "max_score": null, + "hits": [] + }, "aggregations": { "total_weight": { "value": 45.6 @@ -101,13 +108,22 @@ GET /deliveries/_search ``` {% include copy-curl.html %} -The response includes `total_weight_grams` of 45600.0: +The response includes `total_weight_grams` of `45600`: ```json { + ... + "hits": { + "total": { + "value": 4, + "relation": "eq" + }, + "max_score": null, + "hits": [] + }, "aggregations": { "total_weight_grams": { - "value": 45600.0 + "value": 45600 } } } @@ -128,7 +144,7 @@ GET /deliveries/_search "sum": { "field": "weight_kg", "script": { - "source": "_value * 1.1" + "source": "Math.round(_value * 110) / 100.0" } } } @@ -141,6 +157,15 @@ The response reflects a 10% increase applied to the original total weight. ```json { + ... + "hits": { + "total": { + "value": 4, + "relation": "eq" + }, + "max_score": null, + "hits": [] + }, "aggregations": { "adjusted_weight": { "value": 50.16 From 18389fad4967dfed2b7ba61dc8fd04a4a7559714 Mon Sep 17 00:00:00 2001 From: Anton Rubin Date: Thu, 17 Jul 2025 09:17:52 +0100 Subject: [PATCH 3/7] addressing PR comments Signed-off-by: Anton Rubin --- _aggregations/metric/sum.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/_aggregations/metric/sum.md b/_aggregations/metric/sum.md index 866b4d28d97..ff23ff0b7f9 100644 --- a/_aggregations/metric/sum.md +++ b/_aggregations/metric/sum.md @@ -11,6 +11,16 @@ redirect_from: 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. +## Parameters + +The `sum` aggregation takes the following parameters. + +| Parameter | Data type | Description | +| --------- | --------- | ------------------------------------------------------------------------------------------ | +| `field` | string | The field to aggregate on. Must be a numeric field. | +| `script` | object | The script to calculate custom values for aggregation. Can be used instead of or with `field`. | +| `missing` | number | The default value used for documents missing the target field. + ## Example The following example demonstrates how to calculate the total weight of deliveries recorded in a logistics index. From e6668ac4541c7cc2b376e97263c73892a0d21e40 Mon Sep 17 00:00:00 2001 From: Anton Rubin Date: Thu, 17 Jul 2025 09:26:01 +0100 Subject: [PATCH 4/7] addressing PR comments Signed-off-by: Anton Rubin --- _aggregations/metric/sum.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/_aggregations/metric/sum.md b/_aggregations/metric/sum.md index ff23ff0b7f9..d83dd639e29 100644 --- a/_aggregations/metric/sum.md +++ b/_aggregations/metric/sum.md @@ -17,9 +17,9 @@ The `sum` aggregation takes the following parameters. | Parameter | Data type | Description | | --------- | --------- | ------------------------------------------------------------------------------------------ | -| `field` | string | The field to aggregate on. Must be a numeric field. | -| `script` | object | The script to calculate custom values for aggregation. Can be used instead of or with `field`. | -| `missing` | number | The default value used for documents missing the target field. +| `field` | String | The field to aggregate on. Must be a numeric field. | +| `script` | Object | The script to calculate custom values for aggregation. Can be used instead of or with `field`. | +| `missing` | Number | The default value used for documents missing the target field. ## Example From df784605aed885047565c93420a7d1c7ac1f551a Mon Sep 17 00:00:00 2001 From: AntonEliatra Date: Thu, 17 Jul 2025 18:35:02 +0100 Subject: [PATCH 5/7] Apply suggestions from code review Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: AntonEliatra --- _aggregations/metric/sum.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/_aggregations/metric/sum.md b/_aggregations/metric/sum.md index d83dd639e29..e0912b4ef25 100644 --- a/_aggregations/metric/sum.md +++ b/_aggregations/metric/sum.md @@ -19,13 +19,13 @@ The `sum` aggregation takes the following parameters. | --------- | --------- | ------------------------------------------------------------------------------------------ | | `field` | String | The field to aggregate on. Must be a numeric field. | | `script` | Object | The script to calculate custom values for aggregation. Can be used instead of or with `field`. | -| `missing` | Number | The default value used for documents missing the target field. +| `missing` | Number | The default value used for documents missing the target field. | ## Example The following example demonstrates how to calculate the total weight of deliveries recorded in a logistics index. -### Create the index +Create an index: ```json PUT /deliveries @@ -40,7 +40,7 @@ PUT /deliveries ``` {% include copy-curl.html %} -### Add sample documents +Add sample documents: ```json POST /deliveries/_bulk?refresh=true @@ -55,9 +55,8 @@ POST /deliveries/_bulk?refresh=true ``` {% include copy-curl.html %} -### Run the sum aggregation -The following request computes the total weight across all documents in the `deliveries` index, omits document hits and returns the total sum of `weight_kg`: +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`: ```json GET /deliveries/_search @@ -163,7 +162,7 @@ GET /deliveries/_search ``` {% include copy-curl.html %} -The response reflects a 10% increase applied to the original total weight. +The response reflects a 10% increase applied to the original total weight: ```json { @@ -184,7 +183,7 @@ The response reflects a 10% increase applied to the original total weight. } ``` -### Handling missing values +### Missing values Documents missing the target field are ignored by default. To include them using a default value, use the `missing` parameter. This ensures that documents without the field are treated as having zero weight and included in the aggregation. From b3c467b02952788a1842f9f702d66893977ec0ce Mon Sep 17 00:00:00 2001 From: AntonEliatra Date: Thu, 17 Jul 2025 18:40:05 +0100 Subject: [PATCH 6/7] Update sum.md Signed-off-by: AntonEliatra --- _aggregations/metric/sum.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_aggregations/metric/sum.md b/_aggregations/metric/sum.md index e0912b4ef25..14a3b3d4e5a 100644 --- a/_aggregations/metric/sum.md +++ b/_aggregations/metric/sum.md @@ -185,9 +185,9 @@ The response reflects a 10% increase applied to the original total weight: ### Missing values -Documents missing the target field are ignored by default. To include them using a default value, use the `missing` parameter. This ensures that documents without the field are treated as having zero weight and included in the aggregation. +Documents missing the target field are ignored by default. To include them using a default value, use the `missing` parameter. -The following example assigns a default value of `0` for missing `weight_kg` fields: +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 as `0` and included in the aggregation. ```json GET /deliveries/_search From fa0fcc60d3dd8bc8a610960365ee02d894982388 Mon Sep 17 00:00:00 2001 From: Nathan Bower Date: Thu, 17 Jul 2025 14:17:50 -0400 Subject: [PATCH 7/7] Apply suggestions from code review Signed-off-by: Nathan Bower --- _aggregations/metric/sum.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/_aggregations/metric/sum.md b/_aggregations/metric/sum.md index 14a3b3d4e5a..b96f8b193d1 100644 --- a/_aggregations/metric/sum.md +++ b/_aggregations/metric/sum.md @@ -18,7 +18,7 @@ The `sum` aggregation takes the following parameters. | Parameter | Data type | Description | | --------- | --------- | ------------------------------------------------------------------------------------------ | | `field` | String | The field to aggregate on. Must be a numeric field. | -| `script` | Object | The script to calculate custom values for aggregation. Can be used instead of or with `field`. | +| `script` | Object | The script used to calculate custom values for aggregation. Can be used instead of or with `field`. | | `missing` | Number | The default value used for documents missing the target field. | ## Example @@ -73,7 +73,7 @@ GET /deliveries/_search ``` {% include copy-curl.html %} -The response contains value of `45.6` corresponding to the sum of `12.5` + `7.8` + `15.0` + `10.3`: +The response contains the value `45.6`, corresponding to the sum of `12.5` + `7.8` + `15.0` + `10.3`: ```json { @@ -117,7 +117,7 @@ GET /deliveries/_search ``` {% include copy-curl.html %} -The response includes `total_weight_grams` of `45600`: +The response includes the `total_weight_grams` of `45600`: ```json { @@ -140,7 +140,7 @@ The response includes `total_weight_grams` of `45600`: ### Combining a field with a value script -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. +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. The following example increases all weights by 10% before summing: @@ -187,7 +187,7 @@ The response reflects a 10% increase applied to the original total weight: Documents missing the target field are ignored by default. To include them using a default value, use the `missing` parameter. -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 as `0` and included in the aggregation. +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. ```json GET /deliveries/_search