Link Search Menu Expand Document Documentation Menu
Documentation

Stats bucket aggregation

The stats_bucket aggregation is a sibling aggregation that returns a variety of stats (count, min, max, avg, and sum) for the buckets of a previous aggregation.

The specified metric must be numeric, and the sibling aggregation must be a multi-bucket aggregation.

Parameters

The stats_bucket aggregation takes the following parameters.

Parameter Required/Optional Data type Description
buckets_path Required String The path of the aggregation buckets to be aggregated. See Pipeline aggregations.
gap_policy Optional String The policy to apply to missing data. Valid values are skip, insert_zeros, and keep_values. Default is skip.
format Optional String A DecimalFormat formatting string. Returns the formatted output in the aggregation’s <stat>_as_string property.

Example

The following example creates a date histogram with a one-month interval using the OpenSearch Dashboards e-commerce sample data. The sum sub-aggregation calculates the sum of all bytes for each month. Finally, the stats_bucket aggregation returns the count, avg, sum, min, and max stats from these sums:

GET opensearch_dashboards_sample_data_logs/_search
{
  "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"
      }
    }
  }
}

Example response

The aggregation returns all five basic statistics for the buckets:

{
  "took": 4,
  "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
          }
        }
      ]
    },
    "stats_monthly_bytes": {
      "count": 3,
      "min": 2804103,
      "max": 39103067,
      "avg": 26575229.666666668,
      "sum": 79725689
    }
  }
}
350 characters left

Have a question? .

Want to contribute? or .