Date histogram in Elasticsearch - Step-by-Step Execution

Concept Flow - Date histogram

Start: Receive Query

↓

Parse Date Histogram Aggregation

↓

Group Documents by Date Interval

↓

Count Documents per Interval

↓

Return Buckets with Counts

↓

End

The date histogram groups documents by fixed time intervals and counts how many fall into each interval.

Execution Sample

Elasticsearch

{
  "aggs": {
    "sales_over_time": {
      "date_histogram": {
        "field": "date",
        "calendar_interval": "month"
      }
    }
  }
}

This query groups documents by month based on the 'date' field and counts documents in each month.

Execution Table

Step	Action	Input Data	Result
1	Receive query with date_histogram aggregation	{"date": ["2023-01-10", "2023-01-20", "2023-02-05", "2023-02-25", "2023-03-15"]}	Query parsed
2	Parse date_histogram aggregation	calendar_interval = 'month'	Interval set to month
3	Group documents by month	Dates grouped into buckets: Jan 2023, Feb 2023, Mar 2023	Buckets created
4	Count documents in each bucket	Jan: 2 docs, Feb: 2 docs, Mar: 1 doc	Counts calculated
5	Return aggregation result	Buckets with counts	{"buckets": [{"key_as_string": "2023-01-01T00:00:00.000Z", "doc_count": 2}, {"key_as_string": "2023-02-01T00:00:00.000Z", "doc_count": 2}, {"key_as_string": "2023-03-01T00:00:00.000Z", "doc_count": 1}]}

💡 All documents grouped and counted by month, aggregation complete

Variable Tracker

Variable	Start	After Step 3	After Step 4	Final
buckets	empty	{"2023-01": [], "2023-02": [], "2023-03": []}	{"2023-01": 2, "2023-02": 2, "2023-03": 1}	{"buckets": [{"key_as_string": "2023-01-01T00:00:00.000Z", "doc_count": 2}, {"key_as_string": "2023-02-01T00:00:00.000Z", "doc_count": 2}, {"key_as_string": "2023-03-01T00:00:00.000Z", "doc_count": 1}]}

Key Moments - 2 Insights

Why does the date histogram group dates into the first day of each month?

Because the calendar_interval is 'month', Elasticsearch groups all dates in the same month under the bucket key representing the first day of that month, as shown in execution_table step 5.

What happens if a document's date does not fall into any bucket?

All documents with dates within the range are grouped; if a date is outside the data range or missing, it won't appear in any bucket. This is implied in step 3 where only existing dates are grouped.

Visual Quiz - 3 Questions

Look at the execution_table, how many documents are counted in the February 2023 bucket?

A 1

B 3

C 2

D 0

💡 Hint

Check the 'Count documents in each bucket' row in execution_table step 4

At which step does Elasticsearch group documents by the date interval?

A Step 3

B Step 4

C Step 2

D Step 5

💡 Hint

Look for the action describing grouping in execution_table

If the calendar_interval changed to 'week', how would the buckets variable change after step 3?

A Buckets would remain grouped by month

B Buckets would group dates by week instead of month

C Buckets would be empty

D Buckets would group by day

💡 Hint

Refer to variable_tracker and how grouping depends on calendar_interval

Concept Snapshot

Date histogram groups documents by fixed time intervals.
Use 'calendar_interval' to set interval like 'month', 'week', or 'day'.
Each bucket key is the start of the interval.
Counts show how many documents fall into each bucket.
Useful for time series data aggregation.

Full Transcript

The date histogram aggregation in Elasticsearch groups documents by fixed time intervals such as months or weeks. The query specifies the field containing dates and the calendar interval. Elasticsearch parses the query, groups documents by the interval, counts how many documents fall into each group, and returns buckets with counts. Each bucket key represents the start of the interval, for example, the first day of the month. This helps analyze data trends over time by counting documents in each time slice.