Date histogram aggregation #

This multi-bucket aggregation is similar to the normal histogram, but it can only be used with date or date range values. Because dates are represented internally in Elasticsearch as long values, it is possible, but not as accurate, to use the normal histogram on dates as well. The main difference in the two APIs is that here the interval can be specified using date/time expressions. Time-based data requires special support because time-based intervals are not always a fixed length.

Examples #

As an example, here is an aggregation requesting bucket intervals of a month in calendar time:

POST /sales/_search
{
  "aggs": {
    "sales_over_time": {
      "date_histogram": {
        "field": "date",
        "calendar_interval": "1M"
      }
    }
  }
}

Response:

{
  ...
  "aggregations": {
    "sales_over_time": {
      "buckets": [
        {
          "key": 1420070400000,
          "doc_count": 3
        },
        {
          "key": 1422748800000,
          "doc_count": 2
        },
        {
          "key": 1425168000000,
          "doc_count": 2
        }
      ]
    }
  }
}

Parameters for date_histogram #

• field
  (Required, string) Field you wish to aggregate.

calendar_interval #

(Optional, string) Calendar-aware intervals are configured with the calendar_interval parameter. You can specify calendar intervals using the unit name, such as month, or as a single unit quantity, such as 1M. For example, day and 1d are equivalent. Multiple quantities, such as 2d, are not supported.

The accepted calendar intervals are:

• minute, 1m
  All minutes begin at 00 seconds. One minute is the interval between 00 seconds of the first minute and 00 seconds of the following minute in the specified time zone, compensating for any intervening leap seconds, so that the number of minutes and seconds past the hour is the same at the start and end.
• hour, 1h
  All hours begin at 00 minutes and 00 seconds. One hour (1h) is the interval between 00:00 minutes of the first hour and 00:00 minutes of the following hour in the specified time zone, compensating for any intervening leap seconds, so that the number of minutes and seconds past the hour is the same at the start and end.
• day, 1d
  All days begin at the earliest possible time, which is usually 00:00:00 (midnight). One day (1d) is the interval between the start of the day and the start of the following day in the specified time zone, compensating for any intervening time changes.
• week, 1w
  One week is the interval between the start day_of_week:hour:minute:second and the same day of the week and time of the following week in the specified time zone.
• month, 1M
  One month is the interval between the start day of the month and time of day and the same day of the month and time of the following month in the specified time zone, so that the day of the month and time of day are the same at the start and end.
• quarter, 1q
  One quarter is the interval between the start day of the month and time of day and the same day of the month and time of day three months later, so that the day of the month and time of day are the same at the start and end.
• year, 1y
  One year is the interval between the start day of the month and time of day and the same day of the month and time of day the following year in the specified time zone, so that the date and time are the same at the start and end.

fixed_interval #

Fixed intervals are configured with the fixed_interval parameter.

In contrast to calendar-aware intervals, fixed intervals are a fixed number of SI units and never deviate, regardless of where they fall on the calendar. One second is always composed of 1000ms. This allows fixed intervals to be specified in any multiple of the supported units.

However, it means fixed intervals cannot express other units such as months, since the duration of a month is not a fixed quantity. Attempting to specify a calendar interval like month or quarter will throw an exception.

The accepted units for fixed intervals are:

• milliseconds (ms)
  A single millisecond. This is a very, very small interval.
• seconds (s)
  Defined as 1000 milliseconds each.
• minutes (m)
  Defined as 60 seconds each (60,000 milliseconds). All minutes begin at 00 seconds.
• hours (h)
  Defined as 60 minutes each (3,600,000 milliseconds). All hours begin at 00 minutes and 00 seconds.
• days (d)
  Defined as 24 hours (86,400,000 milliseconds). All days begin at the earliest possible time, which is usually 00:00:00 (midnight).