Bucket aggregations (terms, histogram) in Elasticsearch - Step-by-Step Execution

Concept Flow - Bucket aggregations (terms, histogram)

Start Query

↓

Define Aggregation Type

↓

Terms Aggregation

↓

Group by unique terms

↓

Count docs per term

↓

Histogram Aggregation

↓

Define intervals

↓

Group docs by range buckets

↓

Count docs per bucket

↓

Return Aggregation Results

↓

End

The query starts by defining the aggregation type, either terms or histogram, groups documents accordingly, counts documents per bucket, and returns the results.

Execution Sample

Elasticsearch

{
  "aggs": {
    "by_category": {
      "terms": { "field": "category" }
    }
  }
}

This query groups documents by unique 'category' terms and counts how many documents fall into each category.

Execution Table

Step	Aggregation Type	Input Data	Action	Output
1	Terms	Documents with categories: ["books", "books", "toys", "books", "toys"]	Group by unique terms	Buckets: ["books", "toys"]
2	Terms	Buckets: ["books", "toys"]	Count docs per term	{"books": 3, "toys": 2}
3	Histogram	Documents with prices: [5, 12, 17, 22, 27]	Define interval size 10	Buckets: [0-9], [10-19], [20-29]
4	Histogram	Buckets: [0-9], [10-19], [20-29]	Group docs by price range	{"0-9": 1, "10-19": 2, "20-29": 2}
5	End	-	Return aggregation results	Aggregation response with buckets and counts

💡 All documents processed and buckets counted, aggregation complete.

Variable Tracker

Variable	Start	After Step 1	After Step 2	After Step 3	After Step 4	Final
Buckets (Terms)	empty	["books", "toys"]	{"books": 3, "toys": 2}	-	-	{"books": 3, "toys": 2}
Buckets (Histogram)	empty	-	-	[0-9], [10-19], [20-29]	{"0-9": 1, "10-19": 2, "20-29": 2}	{"0-9": 1, "10-19": 2, "20-29": 2}

Key Moments - 3 Insights

Why do terms aggregation buckets only show unique terms?

Because terms aggregation groups documents by unique values of the specified field, as shown in execution_table step 1 where unique terms 'books' and 'toys' form buckets.

How does histogram aggregation decide bucket ranges?

Histogram aggregation uses the defined interval size to create numeric ranges, as in step 3 where interval 10 creates buckets [0-9], [10-19], [20-29].

Why do buckets have counts instead of document lists?

Aggregations count documents per bucket for efficiency; the counts summarize how many documents fall into each bucket, shown in steps 2 and 4.

Visual Quiz - 3 Questions

Look at the execution_table, what is the count for the 'books' bucket after step 2?

A 3

B 2

C 5

D 1

💡 Hint

Check execution_table row with Step 2 under Output column.

At which step does the histogram aggregation define its bucket intervals?

A Step 1

B Step 3

C Step 4

D Step 2

💡 Hint

Look for the step mentioning interval size in execution_table.

If the interval size in histogram aggregation changed from 10 to 5, how would the buckets change?

A Buckets would be larger ranges

B Buckets would stay the same

C Buckets would be smaller ranges, more buckets

D Buckets would disappear

💡 Hint

Refer to variable_tracker for how intervals define bucket ranges.

Concept Snapshot

Bucket Aggregations in Elasticsearch:
- Terms aggregation groups documents by unique field values.
- Histogram aggregation groups numeric values into fixed intervals.
- Each bucket counts documents matching its criteria.
- Results show buckets with doc counts for analysis.
- Useful for grouping and summarizing data quickly.

Full Transcript

This visual execution trace shows how Elasticsearch bucket aggregations work. The process starts by defining the aggregation type: terms or histogram. Terms aggregation groups documents by unique values of a field, creating buckets for each unique term and counting documents in each bucket. Histogram aggregation groups numeric values into fixed-size intervals, creating buckets for ranges and counting documents per range. The execution table traces these steps with example data, showing bucket creation and document counts. The variable tracker shows how bucket contents evolve after each step. Key moments clarify common confusions about bucket uniqueness, interval definition, and why counts are used. The quiz tests understanding of bucket counts, interval steps, and effects of changing interval size. The snapshot summarizes the core ideas for quick reference.