How to Use date_histogram Aggregation in Elasticsearch

Use the date_histogram aggregation in Elasticsearch to group documents by fixed time intervals such as days, weeks, or months. Specify the field containing date values and the calendar_interval or fixed_interval to define the bucket size.

Syntax

The date_histogram aggregation groups documents into buckets based on date intervals. You must specify the field with date values and the calendar_interval or fixed_interval to set the bucket size. Optional parameters include format to control date output and min_doc_count to filter empty buckets.

json

{
  "aggs": {
    "group_by_date": {
      "date_histogram": {
        "field": "date_field",
        "calendar_interval": "day",
        "format": "yyyy-MM-dd",
        "min_doc_count": 1
      }
    }
  }
}

Example

This example shows how to group documents by day using the date_histogram aggregation on the timestamp field. It returns buckets for each day with the count of documents in that day.

json

{
  "size": 0,
  "aggs": {
    "sales_per_day": {
      "date_histogram": {
        "field": "timestamp",
        "calendar_interval": "day",
        "format": "yyyy-MM-dd"
      }
    }
  }
}

Output

{
  "aggregations": {
    "sales_per_day": {
      "buckets": [
        {"key_as_string": "2024-06-01", "doc_count": 10},
        {"key_as_string": "2024-06-02", "doc_count": 7},
        {"key_as_string": "2024-06-03", "doc_count": 5}
      ]
    }
  }
}

Common Pitfalls

• Not specifying calendar_interval or fixed_interval causes errors.
• Using fixed_interval for calendar-aware intervals like months or years can give unexpected results.
• For empty buckets, min_doc_count defaults to 1, so no empty buckets appear unless set to 0.
• Incorrect date formats in the field cause aggregation failures.

json

{
  "aggs": {
    "wrong_interval": {
      "date_histogram": {
        "field": "timestamp"
        /* Missing interval causes error */
      }
    }
  }
}

/* Correct way: */
{
  "aggs": {
    "correct_interval": {
      "date_histogram": {
        "field": "timestamp",
        "calendar_interval": "month"
      }
    }
  }
}

Quick Reference

Parameter	Description	Example Values
field	The date field to aggregate on	"timestamp", "created_at"
calendar_interval	Calendar-aware interval for buckets	"day", "week", "month", "year"
fixed_interval	Fixed time interval in milliseconds or time units	"1d", "1h", "30m"
format	Date format for bucket keys	"yyyy-MM-dd", "yyyy-MM"
min_doc_count	Minimum documents per bucket to include	0, 1

Key Takeaways

Always specify either calendar_interval or fixed_interval to define bucket size.

Use calendar_interval for natural time units like months and years.

Set min_doc_count to 0 to include empty buckets in results.

Format bucket keys with the format parameter for readable dates.

Ensure the date field contains valid date values for aggregation.