In Elasticsearch, what does a terms aggregation return and what does its size parameter control?

## What a bucket aggregation is Elasticsearch splits aggregations into three families. *Metric* aggregations compute a number over a set of documents (`avg`, `sum`, `cardinality`). *Bucket* aggregations do not compute a number — they partition the documents the query matched into groups, and then let you nest more aggregations inside each group. *Pipeline* aggregations post-process the output of other aggregations. The `terms` aggregation is the most-used bucket aggregation and is the direct analogue of a SQL `GROUP BY column`. ## What terms actually returns Given `{"terms": {"field": "tags"}}`, Elasticsearch inspects the values of `tags` in every document that matched the query and produces one bucket per distinct value: ``` "buckets": [ { "key": "kotlin", "doc_count": 190 }, { "key": "java", "doc_count": 155 } ] ``` `key` is the term; `doc_count` is how many matching documents contained it. Because a field can be multi-valued (an array), a single document can contribute to several buckets — the sum of `doc_count` across buckets is therefore not necessarily the number of matching documents. Alongside `buckets` the response carries two bookkeeping fields: `sum_other_doc_count`, the number of matching documents whose term did not make it into the returned buckets, and `doc_count_error_upper_bound`, a bound on how far the returned counts might be off on a multi-shard index. ## size, and what it does not do `size` controls how many buckets are returned, and defaults to 10. Raising it does **not** make Elasticsearch scan less or more of the index — every matching document is visited either way. What `size` changes is how many terms are kept, sorted and shipped back, and how much per-bucket state the coordinating node must hold while merging shard results. That is why a very large `size` on a high-cardinality field is a classic way to trip a circuit breaker: you are asking one node to materialise millions of buckets, not just to read more data. If you want counts only and no documents, set the request-level `"size": 0` so the `hits` array is empty. Note the collision of names: the top-level `size` is the number of search hits, the `size` inside the `terms` object is the number of buckets. ## Ordering and ties The default `order` is `{"_count": "desc"}` — the most frequent terms first — with ties broken by the term ordered ascending. You can order by `_key` instead to get alphabetical or numeric ordering, which is stable and cheap, or by the value of a nested metric sub-aggregation (`{"order": {"avg_price": "desc"}}`). Ordering by a sub-aggregation is legal but produces the least reliable results on a sharded index, because each shard picks its local candidates using that metric before the coordinating node ever sees the whole picture. ## Which fields can you aggregate A `terms` aggregation reads columnar `doc_values`, which are on by default for `keyword`, numeric, `date`, `boolean` and `ip` fields. It does not work out of the box on an analyzed `text` field: `text` has no doc values, and aggregating one requires explicitly enabling in-memory fielddata, which is discouraged. The idiomatic mapping is a `text` field for searching with a `keyword` sub-field (commonly `tags.keyword`) for aggregating and sorting. ## The parameters you will actually use - `order` — as above. - `include` / `exclude` — keep or drop terms by regular expression or by an explicit array of exact values. Useful for stripping a dominant junk term without post-processing. - `min_doc_count` — the minimum count a term needs to be returned; the default is 1, so terms with no matching documents never appear. - `missing` — a value to bucket documents that have no value for the field at all; without it they are simply absent from every bucket. - `shard_size` — how many candidate terms each shard contributes before merging, the main accuracy dial. ## Nesting The real power is composition: any bucket aggregation accepts an `aggs` block that runs once per bucket. `terms` on `status` with a nested `avg` on `amount` gives average order value per status; a `terms` inside a `terms` gives a two-level breakdown, at the cost of multiplying bucket counts (100 outer × 100 inner = 10,000 buckets). Keep an eye on that product — nested `terms` is the usual cause of an aggregation that suddenly needs gigabytes.