OpenSearch Aggregations

https://docs.opensearch.org/latest/aggregations/
Admin
OpenSearch Aggregations documentation covering metric, bucket, and pipeline aggregations for data...
Tokens:134,038
Snippets:994
Trust Score:10
Update:1 month ago
Show doc for...
Tokens:
Raw
### GET /_search (Cardinality Aggregation)

Source: https://docs.opensearch.org/latest/aggregations/metric/cardinality

Example of performing a cardinality aggregation with a specific execution hint.

```APIDOC
## GET /<index>/_search

### Description
Executes a cardinality aggregation on a specified field, optionally using an execution hint to control the underlying collection method.

### Method
GET

### Request Body
- **size** (integer) - Optional - Set to 0 to return only aggregation results.
- **aggs** (object) - Required - The aggregation definition.
  - **cardinality** (object) - Required - Configuration for the cardinality aggregation.
    - **field** (string) - Required - The field to aggregate.
    - **execution_hint** (string) - Optional - The execution strategy: 'direct' or 'ordinals'.

### Request Example
{
  "size": 0,
  "aggs": {
    "unique_products": {
      "cardinality": {
        "field": "products.product_id",
        "execution_hint": "ordinals"
      }
    }
  }
}
```

--------------------------------

### Terms aggregation response example

Source: https://docs.opensearch.org/latest/aggregations/bucket/terms

Example response showing buckets sorted by key in ascending order.

```json
{
  ...
  "aggregations" : {
    "response_codes" : {
      "doc_count_error_upper_bound" : 0,
      "sum_other_doc_count" : 0,
      "buckets" : [
        {
          "key" : "200",
          "doc_count" : 12832
        },
        {
          "key" : "404",
          "doc_count" : 801
        },
        {
          "key" : "503",
          "doc_count" : 441
        }
      ]
    }
  }
}
```

--------------------------------

### Date Histogram Aggregation Examples

Source: https://docs.opensearch.org/latest/aggregations/bucket/date-histogram

Examples demonstrating how to perform date histogram aggregations with custom sorting and scripted value sources.

```APIDOC
## GET /<index>/_search

### Description
Performs a date_histogram aggregation on a specified index to group documents into time intervals.

### Method
GET

### Request Body
- **size** (integer) - Optional - Set to 0 to return only aggregation results.
- **aggs** (object) - Required - The aggregation definition containing the date_histogram configuration.

### Request Example (Sort by Key)
{
  "size": 0,
  "aggs": {
    "recent_months": {
      "date_histogram": {
        "field": "timestamp",
        "calendar_interval": "1M",
        "order": {"_key": "desc"}
      }
    }
  }
}

### Request Example (Sort by Count)
{
  "size": 0,
  "aggs": {
    "busiest_hours": {
      "date_histogram": {
        "field": "timestamp",
        "fixed_interval": "1h",
        "order": {"_count": "desc"}
      }
    }
  }
}

### Request Example (Scripted Value Source)
{
  "size": 0,
  "aggs": {
    "by_hour_script": {
      "date_histogram": {
        "script": {
          "lang": "painless",
          "source": "return doc['timestamp'].value.toInstant().toEpochMilli();"
        },
        "fixed_interval": "1h"
      }
    }
  }
}
```

--------------------------------

### Second derivative response example

Source: https://docs.opensearch.org/latest/aggregations/pipeline/derivative

Example JSON response showing the calculated first and second derivatives within bucket aggregations.

```json
{
  "took": 6,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 10000,
      "relation": "gte"
    },
    "max_score": null,
    "hits": []
  },
  "aggregations": {
    "sales_per_month": {
      "buckets": [
        {
          "key_as_string": "2025-03-01T00:00:00.000Z",
          "key": 1740787200000,
          "doc_count": 480,
          "number_of_bytes": {
            "value": 2804103
          }
        },
        {
          "key_as_string": "2025-04-01T00:00:00.000Z",
          "key": 1743465600000,
          "doc_count": 6849,
          "number_of_bytes": {
            "value": 39103067
          },
          "bytes_1st_deriv": {
            "value": 36298964
          }
        },
        {
          "key_as_string": "2025-05-01T00:00:00.000Z",
          "key": 1746057600000,
          "doc_count": 6745,
          "number_of_bytes": {
            "value": 37818519
          },
          "bytes_1st_deriv": {
            "value": -1284548
          },
          "bytes_2nd_deriv": {
            "value": -37583512
          }
        }
      ]
    }
  }
}
```

--------------------------------

### Scripted metric response

Source: https://docs.opensearch.org/latest/aggregations/metric/scripted-metric

Example output showing the calculated total profit.

```json
{
  ...
  "hits": {
    "total": {
      "value": 4,
      "relation": "eq"
    },
    "max_score": null,
    "hits": []
  },
  "aggregations": {
    "total_profit": {
      "value": 170
    }
  }
}
```

--------------------------------

### Value count response example

Source: https://docs.opensearch.org/latest/aggregations/metric/value-count

Example response showing the aggregation result for a field count.

```json
{
  ...
  "hits": {
    "total": {
      "value": 4675,
      "relation": "eq"
    },
    "max_score": null,
    "hits": []
  },
  "aggregations": {
    "number_of_values": {
      "value": 4675
    }
  }
}
```

--------------------------------

### Nested metric sort response example

Source: https://docs.opensearch.org/latest/aggregations/bucket/terms

Example response showing OS buckets sorted by a nested average bytes metric.

```json
{
  ...
  "aggregations" : {
    "os" : {
      "doc_count_error_upper_bound" : 0,
      "sum_other_doc_count" : 5639,
      "buckets" : [
        {
          "key" : "win xp",
          "doc_count" : 2885,
          "successful" : {
            "doc_count" : 2549,
            "avg_bytes" : {
              "value" : 6083.602196939976
            }
          }
        },
        {
          "key" : "ios",
          "doc_count" : 2737,
          "successful" : {
            "doc_count" : 2512,
            "avg_bytes" : {
              "value" : 5954.860270700637
            }
          }
        },
        {
          "key" : "win 8",
          "doc_count" : 2813,
          "successful" : {
            "doc_count" : 2585,
            "avg_bytes" : {
              "value" : 5910.602321083172
            }
          }
        }
      ]
    }
  }
}
```

--------------------------------

### GET /<index>/_search

Source: https://docs.opensearch.org/latest/aggregations/bucket/composite

Performs a composite aggregation on a specified index. This example demonstrates using sources that match index sort order for improved performance.

```APIDOC
## GET /<index>/_search

### Description
Executes a composite aggregation to bucket data based on defined sources. When sources match the index sort order, the query executes with higher efficiency.

### Method
GET

### Endpoint
/<index>/_search

### Request Body
- **size** (integer) - Optional - The number of buckets to return.
- **aggs** (object) - Required - The aggregation definition containing the composite aggregation.

### Request Example
{
  "size": 0,
  "aggs": {
    "my_buckets": {
      "composite": {
        "size": 1000,
        "sources": [
          { "customer": { "terms": { "field": "customer_id", "order": "asc" } } },
          { "time": { "date_histogram": { "field": "timestamp", "calendar_interval": "1d", "order": "desc" } } }
        ]
      }
    }
  }
}
```

--------------------------------

### Global aggregation response example

Source: https://docs.opensearch.org/latest/aggregations/bucket/global

Example JSON response showing the results of both global and filtered aggregations.

```json
{
  "took": 19,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1633,
      "relation": "eq"
    },
    "max_score": null,
    "hits": []
  },
  "aggregations": {
    "total_avg_amount": {
      "doc_count": 4675,
      "avg_price": {
        "value": 75.05542864304813
      }
    },
    "filtered_avg": {
      "value": 38.363175998928355
    }
  }
}
```

--------------------------------

### Sum Bucket Aggregation Example

Source: https://docs.opensearch.org/latest/aggregations/pipeline/index

This example demonstrates summing the `phpmemory` field within histogram buckets and then summing these bucket sums using `sum_bucket`. The `buckets_path` references the nested `sum_total_memory` aggregation.

```json
GET opensearch_dashboards_sample_data_logs/_search
{
  "size": 0,
  "aggs": {
    "number_of_bytes": {
      "histogram": {
        "field": "bytes",
        "interval": 10000
      },
      "aggs": {
        "sum_total_memory": {
          "sum": {
            "field": "phpmemory"
          }
        }
      }
    },
    "sum_copies": {
      "sum_bucket": {
        "buckets_path": "number_of_bytes>sum_total_memory"
      }
    }
  }
}
```

--------------------------------

### Example response for value script transformation

Source: https://docs.opensearch.org/latest/aggregations/bucket/terms

The expected aggregation output showing the transformed keys.

```json
{
  ...
  "aggregations" : {
    "responses_prefixed" : {
      "doc_count_error_upper_bound" : 0,
      "sum_other_doc_count" : 0,
      "buckets" : [
        {
          "key" : "HTTP 200",
          "doc_count" : 12832
        },
        {
          "key" : "HTTP 404",
          "doc_count" : 801
        },
        {
          "key" : "HTTP 503",
          "doc_count" : 441
        }
      ]
    }
  }
}
```

--------------------------------

### Adjusted weight response

Source: https://docs.opensearch.org/latest/aggregations/metric/sum

Example response showing the result of the scripted transformation.

```json
{
  ...
  "hits": {
    "total": {
      "value": 4,
      "relation": "eq"
    },
    "max_score": null,
    "hits": []
  },
  "aggregations": {
    "adjusted_weight": {
      "value": 50.16
    }
  }
}
```

--------------------------------

### Keyed False Response

Source: https://docs.opensearch.org/latest/aggregations/metric/percentile

Example output showing the array-based format for percentile results.

```json
{
  ...
  "aggregations": {
    "load_time_percentiles": {
      "values": [
        {
          "key": 1,
          "value": 20
        },
        {
          "key": 5,
          "value": 20
        },
        {
          "key": 25,
          "value": 40
        },
        {
          "key": 50,
          "value": 80
        },
        {
          "key": 75,
          "value": 120
        },
        {
          "key": 95,
          "value": 140
        },
        {
          "key": 99,
          "value": 140
        }
      ]
    }
  }
}
```

--------------------------------

### Response with adjusted compression

Source: https://docs.opensearch.org/latest/aggregations/metric/median-absolute-deviation

Example response showing the result of an aggregation with a lower compression setting.

```json
{
  "took": 1,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 10000,
      "relation": "gte"
    },
    "max_score": null,
    "hits": []
  },
  "aggregations": {
    "median_absolute_deviation_DistanceMiles": {
      "value": 1836.265614211182
    }
  }
}
```

--------------------------------

### Create power_usage index

Source: https://docs.opensearch.org/latest/aggregations/metric/stats

Initializes the power_usage index with sample documents containing kwh data.

```json
PUT /power_usage/_bulk?refresh=true
{"index": {}}
{"device_id": "A1", "kwh": 1.2}
{"index": {}}
{"device_id": "A2", "kwh": 0.7}
{"index": {}}
{"device_id": "A3", "kwh": 1.5}
```

--------------------------------

### GET /_search (weighted_avg)

Source: https://docs.opensearch.org/latest/aggregations/metric/weighted-avg

Example of using the weighted_avg aggregation with missing values for both the value and weight fields.

```APIDOC
## GET /<index>/_search

### Description
Calculates the weighted average of a field, allowing for default values when fields are missing using the `missing` parameter.

### Method
GET

### Request Body
- **aggs** (object) - Required - The aggregations definition.
- **aggs.weighted_avg** (object) - Required - The weighted average configuration.
- **aggs.weighted_avg.value** (object) - Required - The field to use for the value, with an optional `missing` parameter.
- **aggs.weighted_avg.weight** (object) - Required - The field to use for the weight, with an optional `missing` parameter.
- **aggs.weighted_avg.format** (string) - Optional - The format for the output value.

### Request Example
{
  "size": 0,
  "aggs": {
    "weighted_rating": {
      "weighted_avg": {
        "value": {
          "field": "rating",
          "missing": 3.0
        },
        "weight": {
          "field": "num_reviews",
          "missing": 1
        },
        "format": "#.##"
      }
    }
  }
}

### Response
#### Success Response (200)
- **aggregations.weighted_rating.value** (number) - The calculated weighted average.
- **aggregations.weighted_rating.value_as_string** (string) - The formatted weighted average.
```

--------------------------------

### Index sample documents

Source: https://docs.opensearch.org/latest/aggregations/bucket/ip-range

Populates the index with sample network log data for testing.

```json
POST /network_logs/_bulk?refresh=true
{"index":{}}
{"ip": "10.0.0.1", "status": "ok"}
{"index":{}}
{"ip": "10.0.0.50", "status": "ok"}
{"index":{}}
{"ip": "10.0.0.100", "status": "error"}
{"index":{}}
{"ip": "10.0.0.200", "status": "ok"}
{"index":{}}
{"ip": "10.0.1.5", "status": "ok"}
{"index":{}}
{"ip": "10.0.1.100", "status": "error"}
{"index":{}}
{"ip": "172.16.0.1", "status": "ok"}
{"index":{}}
{"ip": "172.16.0.50", "status": "ok"}
{"index":{}}
{"ip": "192.168.1.1", "status": "ok"}
{"index":{}}
{"ip": "192.168.1.100", "status": "error"}
```

--------------------------------

### Index product data

Source: https://docs.opensearch.org/latest/aggregations/metric/weighted-avg

Create an index and populate it with product documents, including fields for rating and review counts.

```json
POST _bulk
{ "index": { "_index": "products" } }
{ "name": "Product A", "rating": 4.5, "num_reviews": 100 }
{ "index": { "_index": "products" } }
{ "name": "Product B", "rating": 3.8, "num_reviews": 50 }
{ "index": { "_index": "products" } }
{ "name": "Product C"}
```

--------------------------------

### GET /_search

Source: https://docs.opensearch.org/latest/aggregations/metric/top-hits

Example of using the top_hits aggregation to group results by category and retrieve the most recent order from each.

```APIDOC
## GET /<index>/_search

### Description
This request uses a terms aggregation to group documents by category and a top_hits subaggregation to retrieve the most recent order within each category.

### Method
GET

### Endpoint
/opensearch_dashboards_sample_data_ecommerce/_search

### Request Body
- **size** (integer) - Optional - The number of hits to return for the main search.
- **aggs** (object) - Required - The aggregations to perform, including the top_hits subaggregation.

### Request Example
{
  "size": 0,
  "aggs": {
    "top_categories": {
      "terms": {
        "field": "category.keyword",
        "size": 3
      },
      "aggs": {
        "most_recent_sales": {
          "top_hits": {
            "sort": [
              {
                "order_date": {
                  "order": "desc"
                }
              }
            ],
            "_source": {
              "includes": ["order_date", "taxful_total_price", "customer_full_name"]
            },
            "size": 1
          }
        }
      }
    }
  }
}
```

--------------------------------

### GET my-index/_search

Source: https://docs.opensearch.org/latest/aggregations/bucket/date-range

Example of using the date_range aggregation with a 'missing' parameter to handle documents without a timestamp.

```APIDOC
## GET my-index/_search

### Description
Performs a search request with a date_range aggregation, using the 'missing' parameter to assign a default date to documents lacking a value in the '@timestamp' field.

### Method
GET

### Endpoint
my-index/_search

### Request Body
- **size** (integer) - Optional - The number of hits to return. Set to 0 to return only aggregation results.
- **aggs** (object) - Required - The aggregation definitions.

### Request Example
{
  "size": 0,
  "aggs": {
    "dated_or_undated": {
      "date_range": {
        "field": "@timestamp",
        "missing": "1970-01-01",
        "ranges": [
          { "to": "2000-01-01", "key": "undated_or_old" },
          { "from": "2000-01-01", "key": "dated_recent" }
        ]
      }
    }
  }
}
```

--------------------------------

### GET /_search (bucket_script)

Source: https://docs.opensearch.org/latest/aggregations/pipeline/bucket-script

Example of using the bucket_script aggregation to calculate a value based on parent aggregation metrics.

```APIDOC
## GET /_search

### Description
Executes a search request containing a bucket_script aggregation to perform calculations on aggregated metrics.

### Method
GET

### Endpoint
/{index}/_search

### Parameters
#### Request Body
- **aggs** (object) - Required - The aggregation definitions.
- **bucket_script** (object) - Required - The pipeline aggregation configuration.
- **buckets_path** (object) - Required - Maps script variable names to metrics from parent aggregations.
- **script** (string) - Required - The script to execute using the mapped variables.
- **format** (string) - Optional - The output format for the calculated value.

### Request Example
{
  "size": 0,
  "aggs": {
    "sales_per_month": {
      "date_histogram": {
        "field": "order_date",
        "calendar_interval": "month"
      },
      "aggs": {
        "total_sales": {
          "sum": {
            "field": "taxful_total_price"
          }
        },
        "vendor_count": {
          "cardinality": {
            "field": "products.manufacturer.keyword"
          }
        },
        "avg_vendor_spend": {
          "bucket_script": {
            "buckets_path": {
              "sales": "total_sales",
              "vendors": "vendor_count"
            },
            "script": "params.sales / params.vendors",
            "format": "$#,###.00"
          }
        }
      }
    }
  }
}
```

--------------------------------

### Configure Keyed Parameter

Source: https://docs.opensearch.org/latest/aggregations/metric/percentile-ranks

Demonstrates setting the keyed parameter to false to return results as an array of objects.

```json
GET /transaction_data/_search
{
  "size": 0,
  "aggs": {
    "rank_check": {
      "percentile_ranks": {
        "field": "amount",
        "values": [25, 55],
        "keyed": false
      }
    }
  }
}
```

--------------------------------

### GET /_search (Date Histogram)

Source: https://docs.opensearch.org/latest/aggregations/bucket/date-histogram

Examples of using the date_histogram aggregation to perform time-series bucketing with various configurations.

```APIDOC
## GET /<index>/_search

### Description
Performs a search request with a date_histogram aggregation to group documents by time intervals.

### Method
GET

### Parameters
#### Request Body
- **aggs** (object) - Required - The aggregation definition.
- **aggs.<name>.date_histogram.field** (string) - Required - The date field to bucket.
- **aggs.<name>.date_histogram.fixed_interval** (string) - Optional - Fixed time interval (e.g., "1h").
- **aggs.<name>.date_histogram.calendar_interval** (string) - Optional - Calendar-aware interval (e.g., "day").
- **aggs.<name>.date_histogram.time_zone** (string) - Optional - Time zone for bucket boundaries.
- **aggs.<name>.date_histogram.offset** (string) - Optional - Shift bucket boundaries.
- **aggs.<name>.date_histogram.min_doc_count** (integer) - Optional - Minimum document count to include a bucket.
- **aggs.<name>.date_histogram.extended_bounds** (object) - Optional - Range for empty buckets (min, max).

### Request Example
{
  "size": 0,
  "aggs": {
    "by_hour": {
      "date_histogram": {
        "field": "timestamp",
        "fixed_interval": "1h"
      }
    }
  }
}
```

--------------------------------

### GET /_search

Source: https://docs.opensearch.org/latest/aggregations/pipeline/bucket-sort

Example of using the bucket_sort aggregation to sort date histogram buckets by a sum metric in descending order.

```APIDOC
## GET /<index>/_search

### Description
This request performs a search with a date_histogram aggregation, calculating a sum of bytes per month, and uses the bucket_sort pipeline aggregation to order the resulting buckets by the total bytes in descending order.

### Method
GET

### Endpoint
/<index>/_search

### Request Body
- **size** (integer) - Optional - Set to 0 to return only aggregation results.
- **aggs** (object) - Required - Defines the aggregations to perform, including the parent histogram and the bucket_sort pipeline aggregation.

### Request Example
{
  "size": 0,
  "aggs": {
    "sales_per_month": {
      "date_histogram": {
        "field": "@timestamp",
        "calendar_interval": "month"
      },
      "aggs": {
        "total_bytes": {
          "sum": {
            "field": "bytes"
          }
        },
        "bytes_bucket_sort": {
          "bucket_sort": {
            "sort": [
              { "total_bytes": { "order": "desc" } }
            ]
          }
        }
      }
    }
  }
}
```

--------------------------------

### Using a script for range bucketing

Source: https://docs.opensearch.org/latest/aggregations/bucket/range

Computes values on the fly using a script to apply a markup before bucketing.

```json
GET /opensearch_dashboards_sample_data_ecommerce/_search
{
  "size": 0,
  "aggs": {
    "marked_up_tiers": {
      "range": {
        "script": {
          "source": "doc['taxful_total_price'].value * 1.1"
        },
        "ranges": [
          { "to": 55 },
          { "from": 55, "to": 110 },
          { "from": 110 }
        ]
      }
    }
  }
}
```

--------------------------------

### GET /issues/_search

Source: https://docs.opensearch.org/latest/aggregations/bucket/reverse-nested

An example of using the reverse_nested aggregation to aggregate tags from parent documents while inside a nested comments aggregation.

```APIDOC
## GET /issues/_search

### Description
This request demonstrates how to use the `reverse_nested` aggregation to access parent document fields (like `tags`) while currently scoped within a nested `comments` aggregation.

### Method
GET

### Endpoint
/issues/_search

### Request Body
- **size** (integer) - Optional - The number of hits to return.
- **aggs** (object) - Required - The aggregation definitions, including the `nested` path and the `reverse_nested` aggregation.

### Request Example
{
  "size": 0,
  "aggs": {
    "comments": {
      "nested": {
        "path": "comments"
      },
      "aggs": {
        "top_commenters": {
          "terms": {
            "field": "comments.username"
          },
          "aggs": {
            "back_to_issue": {
              "reverse_nested": {},
              "aggs": {
                "top_tags": {
                  "terms": {
                    "field": "tags"
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

--------------------------------

### GET /_search (Date Histogram Aggregation)

Source: https://docs.opensearch.org/latest/aggregations/bucket/date-histogram

Examples of using the date_histogram aggregation to perform time-based bucketing with various configurations.

```APIDOC
## GET /<index>/_search

### Description
Performs a search request with a date_histogram aggregation to group documents by time intervals.

### Method
GET

### Endpoint
/<index>/_search

### Request Body
- **aggs** (object) - Required - The aggregation definition containing the date_histogram.
- **size** (integer) - Optional - Set to 0 to return only aggregation results.

### Request Example
{
  "size": 0,
  "aggs": {
    "strict_range": {
      "date_histogram": {
        "field": "timestamp",
        "fixed_interval": "30m",
        "hard_bounds": {"min": "2025-09-01T00:00:00Z", "max": "2025-09-01T06:00:00Z"}
      }
    }
  }
}
```

--------------------------------

### Example response for min_bucket

Source: https://docs.opensearch.org/latest/aggregations/pipeline/min-bucket

The response includes the calculated minimum value and the keys of the buckets where that minimum was observed.

```json
{
  "took": 7,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 10000,
      "relation": "gte"
    },
    "max_score": null,
    "hits": []
  },
  "aggregations": {
    "visits_per_month": {
      "buckets": [
        {
          "key_as_string": "2025-03-01T00:00:00.000Z",
          "key": 1740787200000,
          "doc_count": 480,
          "sum_of_bytes": {
            "value": 2804103
          }
        },
        {
          "key_as_string": "2025-04-01T00:00:00.000Z",
          "key": 1743465600000,
          "doc_count": 6849,
          "sum_of_bytes": {
            "value": 39103067
          }
        },
        {
          "key_as_string": "2025-05-01T00:00:00.000Z",
          "key": 1746057600000,
          "doc_count": 6745,
          "sum_of_bytes": {
            "value": 37818519
          }
        }
      ]
    },
    "min_monthly_bytes": {
      "value": 2804103,
      "keys": [
        "2025-03-01T00:00:00.000Z"
      ]
    }
  }
}
```

--------------------------------

### Moving Function Aggregation Response

Source: https://docs.opensearch.org/latest/aggregations/pipeline/moving-function

Example response showing the calculated moving function values starting from the third bucket.

```json
{
  "took": 7,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 4675,
      "relation": "eq"
    },
    "max_score": null,
    "hits": []
  },
  "aggregations": {
    "my_date_histo": {
      "buckets": [
        {
          "key_as_string": "2025-03-24T00:00:00.000Z",
          "key": 1742774400000,
          "doc_count": 582,
          "the_sum": {
            "value": 41455.5390625
          },
          "the_movavg": {
            "value": null
          }
        },
        {
          "key_as_string": "2025-03-31T00:00:00.000Z",
          "key": 1743379200000,
          "doc_count": 1048,
          "the_sum": {
            "value": 79448.60546875
          },
          "the_movavg": {
            "value": null
          }
        },
        {
          "key_as_string": "2025-04-07T00:00:00.000Z",
          "key": 1743984000000,
          "doc_count": 1048,
          "the_sum": {
            "value": 78208.4296875
          },
          "the_movavg": {
            "value": 79448.60546875
          }
        },
        {
          "key_as_string": "2025-04-14T00:00:00.000Z",
          "key": 1744588800000,
          "doc_count": 1073,
          "the_sum": {
            "value": 81277.296875
          },
          "the_movavg": {
            "value": 79448.60546875
          }
        },
        {
          "key_as_string": "2025-04-21T00:00:00.000Z",
          "key": 1745193600000,
          "doc_count": 924,
          "the_sum": {
            "value": 70494.2578125
          },
          "the_movavg": {
            "value": 81277.296875
          }
        }
      ]
    }
  }
}
```

--------------------------------

### Example index data

Source: https://docs.opensearch.org/latest/aggregations/bucket/composite

Sample document structure for marathon participants used to demonstrate composite aggregation.

```json
{
  ... "city": "Albuquerque", "place": "Bronze" ...}
{... "city": "Boston",  ...}
{... "city": "Chicago", "place": "Bronze" ...}
{... "city": "Albuquerque", "place": "Gold" ...}
{... "city": "Chicago", "place": "Silver" ...}
{... "city": "Boston", "place": "Bronze" ...}
{... "city": "Chicago", "place": "Gold" ...}

```

--------------------------------

### Bulk index sample documents

Source: https://docs.opensearch.org/latest/aggregations/metric/scripted-metric

Adds sample log entries with various HTTP response codes to the index.

```json
PUT logs/_bulk?refresh=true
{ "index": {} }
{ "response": "200" }
{ "index": {} }
{ "response": "201" }
{ "index": {} }
{ "response": "404" }
{ "index": {} }
{ "response": "500" }
{ "index": {} }
{ "response": "304" }
```

--------------------------------

### GET /<index>/_search

Source: https://docs.opensearch.org/latest/aggregations/bucket/filter

Example of using the filter aggregation to calculate the average order total for documents matching a range query.

```APIDOC
## GET /<index>/_search

### Description
Calculates aggregations on a subset of documents defined by a filter query.

### Method
GET

### Endpoint
/<index>/_search

### Request Body
- **aggs** (object) - Required - The aggregation definitions, including the filter aggregation.

### Request Example
{
  "size": 0,
  "aggs": {
    "low_value": {
      "filter": {
        "range": {
          "taxful_total_price": {
            "lte": 50
          }
        }
      },
      "aggs": {
        "avg_amount": {
          "avg": {
            "field": "taxful_total_price"
          }
        }
      }
    }
  }
}

### Response
#### Success Response (200)
- **doc_count** (Integer) - The number of documents that matched the filter query.

#### Response Example
{
  "aggregations": {
    "low_value": {
      "doc_count": 1633,
      "avg_amount": {
        "value": 38.363175998928355
      }
    }
  }
}
```

--------------------------------

### GET /_search (stats_bucket aggregation)

Source: https://docs.opensearch.org/latest/aggregations/pipeline/stats-bucket

Example of using the stats_bucket aggregation within a search request to calculate statistics on the results of a date_histogram aggregation.

```APIDOC
## GET /_search

### Description
Performs a search request that includes a stats_bucket aggregation to calculate statistics across buckets generated by a parent aggregation.

### Parameters
#### Request Body
- **aggs** (object) - Required - The aggregation definitions.
- **buckets_path** (string) - Required - The path of the aggregation buckets to be aggregated.
- **gap_policy** (string) - Optional - The policy to apply to missing data (skip or insert_zeros).
- **format** (string) - Optional - A DecimalFormat formatting string.

### Request Example
{
  "size": 0,
  "aggs": {
    "visits_per_month": {
      "date_histogram": {
        "field": "@timestamp",
        "interval": "month"
      },
      "aggs": {
        "sum_of_bytes": {
          "sum": {
            "field": "bytes"
          }
        }
      }
    },
    "stats_monthly_bytes": {
      "stats_bucket": {
        "buckets_path": "visits_per_month>sum_of_bytes"
      }
    }
  }
}

### Response
#### Success Response (200)
- **aggregations** (object) - Contains the calculated stats (count, min, max, avg, sum) for the specified buckets.

#### Response Example
{
  "aggregations": {
    "stats_monthly_bytes": {
      "count": 3,
      "min": 2804103,
      "max": 39103067,
      "avg": 26575229.666666668,
      "sum": 79725689
    }
  }
}
```

--------------------------------

### GET /<index>/_search

Source: https://docs.opensearch.org/latest/aggregations/pipeline/derivative

Example of using the derivative aggregation within a date histogram to calculate the change in sum of bytes between consecutive months.

```APIDOC
## GET /<index>/_search

### Description
Calculates the first derivative of a metric subaggregation across buckets. The derivative is computed as the difference between the current bucket's value and the previous bucket's value.

### Method
GET

### Request Body
- **aggs** (object) - Required - The aggregation definitions.
- **buckets_path** (string) - Required - The path to the metric subaggregation to use for the derivative calculation.

### Request Example
{
  "size": 0,
  "aggs": {
    "sales_per_month": {
      "date_histogram": {
        "field": "@timestamp",
        "calendar_interval": "month"
      },
      "aggs": {
        "number_of_bytes": {
          "sum": {
            "field": "bytes"
          }
        },
        "bytes_deriv": {
          "derivative": {
            "buckets_path": "number_of_bytes"
          }
        }
      }
    }
  }
}

### Response
#### Success Response (200)
- **aggregations** (object) - Contains the results of the aggregations, including the calculated derivative values.

#### Response Example
{
  "aggregations": {
    "sales_per_month": {
      "buckets": [
        {
          "key_as_string": "2025-03-01T00:00:00.000Z",
          "number_of_bytes": { "value": 2804103 }
        },
        {
          "key_as_string": "2025-04-01T00:00:00.000Z",
          "number_of_bytes": { "value": 39103067 },
          "bytes_deriv": { "value": 36298964 }
        }
      ]
    }
  }
}
```

--------------------------------

### Add sample documents to the index

Source: https://docs.opensearch.org/latest/aggregations/metric/sum

Uses the bulk API to insert sample delivery records.

```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}
```

--------------------------------

### Stats aggregation response example

Source: https://docs.opensearch.org/latest/aggregations/metric/stats

Example response structure returned by the stats aggregation.

```json
{
  ...
  "hits": {
    "total": {
      "value": 3,
      "relation": "eq"
    },
    "max_score": null,
    "hits": []
  },
  "aggregations": {
    "usage_wh_stats": {
      "count": 3,
      "min": 699.999988079071,
      "max": 1500,
      "avg": 1133.3333452542622,
      "sum": 3400.000035762787
    }
  }
}
```

--------------------------------

### Create index for scripted metric

Source: https://docs.opensearch.org/latest/aggregations/metric/scripted-metric

Initializes an index with a keyword field for response codes.

```json
PUT logs
{
  "mappings": {
    "properties": {
      "response": { "type": "keyword" }
    }
  }
}
```

--------------------------------

### Example response for keyed aggregation

Source: https://docs.opensearch.org/latest/aggregations/bucket/geo-distance

Shows the structure of the response when the keyed parameter is set to true.

```json
{
  "took": 18,
  "timed_out": false,
  "terminated_early": true,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 4675,
      "relation": "eq"
    },
    "max_score": null,
    "hits": []
  },
  "aggregations": {
    "distance_from_nyc": {
      "buckets": {
        "local": {
          "from": 0.0,
          "to": 50.0,
          "doc_count": 896
        },
        "domestic": {
          "from": 50.0,
          "to": 500.0,
          "doc_count": 0
        },
        "international": {
          "from": 500.0,
          "doc_count": 3779
        }
      }
    }
  }
}
```

--------------------------------

### Histogram Response Example

Source: https://docs.opensearch.org/latest/aggregations/bucket/histogram

Example JSON response structure returned by a histogram aggregation.

```json
{
  "took": 2,
  "timed_out": false,
  "terminated_early": true,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 4675,
      "relation": "eq"
    },
    "max_score": null,
    "hits": []
  },
  "aggregations": {
    "price_histogram": {
      "buckets": [
        {
          "key": 0.0,
          "doc_count": 1633
        },
        {
          "key": 50.0,
          "doc_count": 2036
        },
        {
          "key": 100.0,
          "doc_count": 724
        },
        {
          "key": 150.0,
          "doc_count": 205
        },
        {
          "key": 200.0,
          "doc_count": 53
        },
        {
          "key": 250.0,
          "doc_count": 14
        },
        {
          "key": 300.0,
          "doc_count": 7
        },
        {
          "key": 350.0,
          "doc_count": 2
        },
        {
          "key": 2250.0,
          "doc_count": 1
        }
      ]
    }
  }
}
```

--------------------------------

### Create index with geo_point mapping

Source: https://docs.opensearch.org/latest/aggregations/bucket/geotile-grid

Initializes an index named national_parks with a location field mapped as a geo_point.

```json
PUT national_parks
{
  "mappings": {
    "properties": {
      "location": {
        "type": "geo_point"
      }
    }
  }
}
```

--------------------------------

### Example response for sliding windows

Source: https://docs.opensearch.org/latest/aggregations/bucket/date-range

The expected aggregation response structure showing the calculated buckets and document counts.

```json
"aggregations": {
    "by_range": {
      "buckets": [
        {
          "key": "older",
          "to": 1758067200000,
          "to_as_string": "2025-09-17",
          "doc_count": 1
        },
        {
          "key": "prev_7d",
          "from": 1758067200000,
          "from_as_string": "2025-09-17",
          "to": 1758672000000,
          "to_as_string": "2025-09-24",
          "doc_count": 2
        },
        {
          "key": "last_7d",
          "from": 1758672000000,
          "from_as_string": "2025-09-24",
          "to": 1759363200000,
          "to_as_string": "2025-10-02",
          "doc_count": 2
        }
      ]
    }
  }
```

--------------------------------

### Geo-bounds aggregation response example

Source: https://docs.opensearch.org/latest/aggregations/metric/geobounds

Example of the JSON response structure returned by the geo-bounds aggregation.

```json
{
...
  "aggregations": {
    "grouped": {
      "bounds": {
        "top_left": {
          "lat": 45.11999997776002,
          "lon": -120.23000006563962
        },
        "bottom_right": {
          "lat": 13.469999986700714,
          "lon": 144.71999991685152
        }
      }
    }
  }
}
```

--------------------------------

### Configure cardinality aggregation execution hint

Source: https://docs.opensearch.org/latest/aggregations/metric/cardinality

Demonstrates how to force the use of ordinals for a cardinality aggregation using the execution_hint parameter.

```json
GET opensearch_dashboards_sample_data_ecommerce/_search
{
  "size": 0,
  "aggs": {
    "unique_products": {
      "cardinality": {
        "field": "products.product_id",
        "execution_hint": "ordinals"
      }
    }
  }
}
```

--------------------------------

### Nested aggregation response example

Source: https://docs.opensearch.org/latest/aggregations/bucket/nested

Example of the JSON response structure returned after executing a nested aggregation.

```json
"hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 1,
    "hits": [
      {
        "_index": "logs-nested",
        "_id": "0",
        "_score": 1,
        "_source": {
          "response": "200",
          "pages": [
            {
              "page": "landing",
              "load_time": 200
            },
            {
              "page": "blog",
              "load_time": 500
            }
          ]
        }
      }
    ]
  },
  "aggregations": {
    "pages": {
      "doc_count": 2,
      "min_load_time": {
        "value": 200
      }
    }
  }
```

--------------------------------

### Significant Terms Aggregation Examples

Source: https://docs.opensearch.org/latest/aggregations/bucket/significant-terms

Examples demonstrating how to use significant_terms within terms and geotile_grid aggregations to identify outliers.

```APIDOC
## GET /<index>/_search

### Description
Performs a significant_terms aggregation to identify terms that are disproportionately common within specific buckets.

### Method
GET

### Endpoint
/{index}/_search

### Request Body
- **size** (integer) - Optional - Set to 0 to exclude search hits from the response.
- **aggs** (object) - Required - The aggregation definition containing the significant_terms aggregation.

### Request Example
{
  "size": 0,
  "aggs": {
    "by_region": {
      "terms": { "field": "region.keyword", "size": 5 },
      "aggs": {
        "odd_cancellations": {
          "significant_terms": { "field": "cancel_reason.keyword" }
        }
      }
    }
  }
}
```

--------------------------------

### POST /products/_doc

Source: https://docs.opensearch.org/latest/aggregations/metric/weighted-avg

Indexes a document with multi-valued fields for use in weighted average calculations.

```APIDOC
## POST /products/_doc

### Description
Indexes a document with a multi-valued rating field and a single-valued weight field.

### Method
POST

### Endpoint
/products/_doc?refresh=true

### Request Body
- **name** (string) - Required - The name of the product.
- **rating** (array) - Required - A list of numeric ratings.
- **num_reviews** (number) - Required - The weight value for the ratings.
```
Tokens:
Raw