You have a million documents in an index, and a manager asks a simple question: how many cars did we list for each make, and what is the average price of each? You do not need to read a million documents to answer. Elasticsearch can group them and do the maths inside the cluster, and return a few lines of numbers. That is what aggregations are for.
An aggregation summarises your data. It can count documents in groups, calculate an average or a total, show how prices spread over ranges, or work on the results of other aggregations. If you have used GROUP BY in SQL, the idea will feel familiar. Aggregations are also the engine behind the charts and tables in Kibana.
In this guide we explain the aggs request, and the three types of aggregations. We then build a small index of cars, and run the three examples from the original page, this time with the full request text, so you can copy them. After that we add the things that most beginners miss: size 0, the keyword field rule, the default of 10 buckets, query scope, range and histogram, and a pipeline example.
Every aggregation lives inside the aggs parameter of a search request. You give each aggregation a name of your choice, and the name appears again in the response. The simplest form looks like this, with a placeholder name and field:
The word aggs is a short form. You can also write aggregations in full, and both work. Elastic also documents that you can set size to 0 when you want only the aggregation results, and no search hits. We use that in every example below.
Elasticsearch groups aggregations into three families.
| Family | What it does | Examples |
|---|---|---|
| Bucket | Groups documents into buckets, based on field values, ranges or other rules. Each bucket has a document count | terms, range, histogram, date_histogram |
| Metric | Calculates a value from the field values, such as a sum or an average | avg, min, max, sum, value_count, stats, cardinality |
| Pipeline | Takes its input from other aggregations, and not from documents or fields | avg_bucket, sum_bucket, derivative |
The old page said that a metric aggregation computes a single statistic. That is true for avg, min, max and sum, which return one value. But stats returns five values, which are count, min, max, avg and sum. So it is better to say that a metric aggregation calculates numbers from field values, and that some return one value while others return several.
The old page used a cars example, and showed the queries only as pictures. To make the examples copyable, here is a small index of 10 cars. Run these two requests in Kibana Dev Tools. The first creates the index with the right field types. The second adds the documents. The refresh=true setting makes them searchable at once.
Notice that make, model and color are keyword fields, and year and price are integers. This matters. The terms aggregation works on keyword fields, and we explain why below.
| Make | Model | Year | Price | Color |
|---|---|---|---|---|
| Toyota | Corolla | 2022 | 21000 | white |
| Toyota | Camry | 2023 | 28000 | black |
| Toyota | Fortuner | 2021 | 41000 | white |
| Toyota | Yaris | 2020 | 14000 | silver |
| Honda | City | 2022 | 19000 | silver |
| Honda | Civic | 2023 | 26000 | black |
| Honda | Amaze | 2021 | 12000 | white |
| Ford | Figo | 2020 | 11000 | white |
| Ford | Endeavour | 2022 | 44000 | grey |
| BMW | X1 | 2023 | 52000 | black |
The responses below are shown for this data, and trimmed to the aggregations part. A real response also has fields such as took and hits.
The first example from the old page groups the cars by make, in an aggregation called popular_cars. The terms aggregation makes one bucket for each different value in the field, and counts the documents in each.

Read the response like this. There are 4 Toyota cars, 3 Honda, 2 Ford and 1 BMW. The buckets are sorted with the biggest count first, which is the default. The field sum_other_doc_count is 0, which means no documents were left out. The field doc_count_error_upper_bound is also 0, which means the counts are exact here. We explain both below.
A search request returns the top 10 matching documents by default, as well as the aggregations. If you only want the numbers, setting size to 0 skips the documents and keeps the response small. Elastic also notes that using size 0 together with the same preference string for each search can let you use the shard request cache for repeat queries.
To see how it looks when you do want both, here is a request that returns the two most expensive cars, and the make counts, in one response:
You can put several aggregations in one request, and Elasticsearch runs them all on the same set of documents. The old example ran popular_cars with avg_price, max_price and min_price.

The three metric aggregations work on all 10 cars. The average is 26800, the highest price is 52000 and the lowest is 11000. Note that metric values come back as decimals, such as 26800.0, even for an integer field. Also note that these three numbers are not per make. They cover the whole set, because the metric aggregations sit next to popular_cars and not inside it. To get them per make, you need nesting, which is Example 3.
A bucket aggregation can hold other aggregations inside it, and they run once for every bucket. These are called sub aggregations. Here the stats aggregation runs inside each make bucket. The Elastic documentation says that there is no limit on how deep you can nest, but each level adds work, so keep it as shallow as you can.
Now every make has its own count, minimum, maximum, average and sum. For example, the 4 Toyotas have an average price of 26000, and the single BMW has an average of 52000. The old page said that stats gives the average, minimum, maximum and sum. As you can see, it also gives the count.
By default the buckets are sorted by document count. You can sort them by the result of a sub aggregation instead. Here the makes are ordered by average price, with the most expensive first.
The Elastic documentation advises care with ordering by a sub aggregation, and warns that ordering by ascending count gives inaccurate results. For rare values, it points to the rare_terms aggregation.
A terms aggregation returns the top 10 terms by default. Use size to get more or fewer, up to the limit set by the search.max_buckets setting of the cluster. Here is a request for only the top 2 makes:
Now sum_other_doc_count is 3. This is the number of documents in the terms that did not make it into the top 2. Ford has 2 and BMW has 1, so 3 documents were left out. If this number is above 0 in your own data, some buckets were dropped, and you should raise size.
Aggregations run on the documents that match the query. If you add a query, the aggregation sees only those documents. Here we count the colours of cars that cost at least 20000:
Four cars cost less than 20000, so they are left out of the counts. Without the query, white would have 4.
Besides avg, min, max and stats, three more are used all the time.
sum adds up the values of a field.value_count counts how many values the field has.cardinality counts how many different values the field has.The cardinality aggregation gives an approximate count for large data. For a tiny set like ours it is exact. The result of 4 matches the four makes we saw earlier.
A whole set of numbers in one go is also available with stats, as in Example 3, but on the whole index:
The terms aggregation works well for labels. For numbers, you often want bands. The range aggregation makes buckets that you define. Here three price bands are named budget, mid and premium. The from value is included, and the to value is not.
The histogram aggregation makes equal sized steps. Here the step is 10000. Empty steps in the middle are shown with a count of 0.
There is also the date_histogram aggregation, which groups documents by a time step such as a day or a month. It is the one behind most time charts in Kibana. Our sample has no date field, so I have not run it here. Please add a date field to your own data to try it.
A pipeline aggregation takes its input from other aggregations. Here avg_bucket finds the average of the average prices of all the makes. The path to the input uses the greater than sign to go from the bucket aggregation to the metric inside it.
The average of the four make averages is 31125. This is different from the overall average of 26800 in Example 2. The reason is that the overall average counts each car once, so Toyota, with 4 cars, has more weight. The pipeline average counts each make once. Neither is wrong, but they answer different questions, and you should pick the one that fits.
The most common beginner problem is running a terms aggregation on a text field. A text field is split into words for search, and is not meant for grouping. The Elastic documentation says that you cannot run a terms aggregation on a text field by default. There are two ways round it.
fielddata for the text field. This can use a lot of memory.If you let Elasticsearch map a new text field on its own, it usually makes a text field with a keyword sub field named keyword. You can also do this yourself:
Then you aggregate on the sub field, make.keyword:
I could not run this error here, so I have not quoted the exact error text. Check it on your own cluster. It is an illegal argument error, and it tells you to use a keyword field.
doc_count_error_upper_bound tells you the largest possible error. The Elastic documentation says to set show_term_doc_count_error to true if you want this value per bucket. The shard_size setting, which defaults to size times 1.5 plus 10, controls how many terms each shard returns.search.max_buckets setting limits how many buckets one request may create.typed_keys. The meta option adds your own note to an aggregation. The typed_keys option adds the aggregation type to the name in the response, such as terms#popular_cars.If you know SQL, this table links the ideas. This is an idea map, and I am not claiming that one is faster than the other. That depends on your data, your hardware and your setup.
| SQL | Elasticsearch | Where to find it |
|---|---|---|
| GROUP BY make | terms on make | Example 1 |
| COUNT, AVG, MIN, MAX | value_count, avg, min, max | Example 2 |
| GROUP BY with AVG per group | terms with an avg sub aggregation | Example 3 |
| WHERE price >= 20000 | a range query next to the aggs | Query scope section |
| CASE WHEN price bands | range aggregation | Range section |
| COUNT DISTINCT make | cardinality | Metrics section |
The SQL for Example 3 would look like this:
One difference matters. A SQL query runs on tables that you design for joins and exact answers. Elasticsearch is built for search first, and for fast summaries on large amounts of data. It does not do joins in the same way, so check that it fits your task before you move work from a database.

The old page said that one query can replace several SQL queries and a lot of application code, and that Elasticsearch is faster than an RDBMS. It gave no example or test. Here is what you can show. In a single request, Example 3 gave a count and five statistics for every make. Doing the same without aggregations would mean fetching documents and calculating in your own code.
That is the real value. The summary is built where the data lives, so only a few lines travel over the network. This is why aggregations are used for dashboards, log analysis, product filters on shopping sites, and reports on search data.
How fast it runs depends on the size of your data, the number of shards, the field types and how many buckets you ask for. If you plan to use it for analytics at work, test with your own data.
| Problem | Usual cause | Fix |
|---|---|---|
| An error on a terms aggregation | The field is a text field | Use a keyword field or a keyword sub field |
| The response is full of hits | size was not set to 0 | Add size 0 |
| Only 10 buckets come back | The default size of a terms aggregation is 10 | Set size, and check sum_other_doc_count |
| The metric numbers are for all documents, not per group | The metric is next to the bucket, not inside it | Put the metric in the aggs of the bucket aggregation |
| Counts look slightly wrong on a large index | Terms counts are approximate across shards | Raise shard_size, and check doc_count_error_upper_bound |
| The average has a long decimal | Metric values are doubles | Round the number in your app |
| The aggregation name is not found in the response | Names are your own, and are case sensitive | Use the exact name from your request |
Aggregations turn Elasticsearch from a search box into an analysis tool. Start with one terms aggregation on a keyword field, add one metric inside it, and add a query to narrow the data. Once that is comfortable, move on to range, date_histogram and pipeline aggregations. A good next step is to build a Kibana chart from the same index, because Kibana runs these same aggregations behind every chart.