NOTE: You are looking at documentation for an older release. For the latest information, see the current release documentation.
Bucket aggregations don’t calculate metrics over fields like the metrics aggregations do, but instead, they create
buckets of documents. Each bucket is associated with a criterion (depending on the aggregation type) which determines
whether or not a document in the current context "falls" into it. In other words, the buckets effectively define document
sets. In addition to the buckets themselves, the
bucket aggregations also compute and return the number of documents
that "fell into" each bucket.
Bucket aggregations, as opposed to
metrics aggregations, can hold sub-aggregations. These sub-aggregations will be
aggregated for the buckets created by their "parent" bucket aggregation.
There are different bucket aggregators, each with a different "bucketing" strategy. Some define a single bucket, some define fixed number of multiple buckets, and others dynamically create the buckets during the aggregation process.
The maximum number of buckets allowed in a single response is limited by a dynamic cluster
search.max_buckets. It is disabled by default (-1) but requests that try to return more than
10,000 buckets (the default value for future versions) will log a deprecation warning.
When using composite aggs however, the handling of -1 differs. Elasticsearch would use the soft limit as a
hard limit for those aggregations, and raise a
Trying to create too many buckets. Must be less than or equal to:  if the soft limit is exceeded.