From 5cec077ca9e3d8713796b17be7e35ec1aba5b9f1 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Thu, 17 Jul 2025 18:24:43 +0000 Subject: [PATCH] adding sum aggregations docs (#10256) * adding sum aggregations docs Signed-off-by: Anton Rubin * fixing vale errors Signed-off-by: Anton Rubin * addressing PR comments Signed-off-by: Anton Rubin * addressing PR comments Signed-off-by: Anton Rubin * Apply suggestions from code review Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: AntonEliatra * Update sum.md Signed-off-by: AntonEliatra * Apply suggestions from code review Signed-off-by: Nathan Bower --------- Signed-off-by: Anton Rubin Signed-off-by: AntonEliatra Signed-off-by: Nathan Bower Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Co-authored-by: Nathan Bower (cherry picked from commit 20853e7271dbe401c47b88b3bc20fbbeb4ea7182) Signed-off-by: github-actions[bot] --- _aggregations/metric/sum.md | 181 ++++++++++++++++++++++++++++++++---- 1 file changed, 165 insertions(+), 16 deletions(-) diff --git a/_aggregations/metric/sum.md b/_aggregations/metric/sum.md index 2e0b32cb3dd..b96f8b193d1 100644 --- a/_aggregations/metric/sum.md +++ b/_aggregations/metric/sum.md @@ -9,18 +9,107 @@ 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: +## 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 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 + +The following example demonstrates how to calculate the total weight of deliveries recorded in a logistics index. + +Create an index: + +```json +PUT /deliveries +{ + "mappings": { + "properties": { + "shipment_id": { "type": "keyword" }, + "weight_kg": { "type": "double" } + } + } +} +``` +{% 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 %} + + +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 +{ + "size": 0, + "aggs": { + "total_weight": { + "sum": { + "field": "weight_kg" + } + } + } +} +``` +{% include copy-curl.html %} + +The response contains the value `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 + } + } +} +``` + +### 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 +117,90 @@ GET opensearch_dashboards_sample_data_ecommerce/_search ``` {% include copy-curl.html %} -#### Example response +The response includes the `total_weight_grams` of `45600`: ```json { - "took": 16, - "timed_out": false, - "_shards": { - "total": 1, - "successful": 1, - "skipped": 0, - "failed": 0 + ... + "hits": { + "total": { + "value": 4, + "relation": "eq" + }, + "max_score": null, + "hits": [] }, + "aggregations": { + "total_weight_grams": { + "value": 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. + +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": "Math.round(_value * 110) / 100.0" + } + } + } + } +} +``` +{% include copy-curl.html %} + +The response reflects a 10% increase applied to the original total weight: + +```json +{ + ... "hits": { "total": { - "value": 4675, + "value": 4, "relation": "eq" }, "max_score": null, "hits": [] }, "aggregations": { - "sum_taxful_total_price": { - "value": 350884.12890625 + "adjusted_weight": { + "value": 50.16 + } + } +} +``` + +### Missing values + +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 to `0` and included in the aggregation. + +```json +GET /deliveries/_search +{ + "size": 0, + "aggs": { + "total_weight_with_missing": { + "sum": { + "field": "weight_kg", + "missing": 0 + } } } } ``` +{% include copy-curl.html %}