Auto date histogram aggregation #

A multi-bucket aggregation like date_histogram, but you choose the NUMBER of buckets and the engine picks the interval that best fits. It solves the cold-start problem of time charts: when you do not know whether the data spans minutes or years, you state the resolution you want on screen and let the ladder decide the unit.

How it works #

The engine reads every date value (epoch milliseconds), takes the data extent max − min, and divides by the buckets target to get a rough per-bucket width. That width is matched against a fixed ladder, and the smallest interval that covers it wins: 1s, 1m, 5m, 10m, 30m, 1h, 6h, 12h, 1d, 1w as fixed intervals; beyond a week the calendar units month, quarter, year (and multi-year multiples for very long extents). The pick is one closed-form step, not an iterative search.

Fixed-interval grids anchor at the data minimum; calendar picks floor to civil boundaries (month starts, quarter starts, year starts), so bucket keys stay on human dates. Documents are then assigned to the grid points, capped at 100,000 buckets as a runaway guard.

Each bucket reports key (the boundary as epoch milliseconds) and doc_count. The engine does not echo the chosen interval next to the result — infer it from the key spacing, or compare with an explicit date_histogram.

Example #

Ask for three buckets over the sales timeline:

The 120 teaching sales span 2024-01-01 to 2025-04-21 — a rough width of ~5.2 months per bucket, which the ladder rounds up to year. The response carries two buckets: 2024-01-01 (92 sales) and 2025-01-01 (28 sales). With the default buckets: 10 the same span picks quarter and returns six buckets (23/23/23/23/22/6).

Use cases #

• Exploring an unfamiliar date field. First contact with a new dataset: one auto_date_histogram tells you its true timescale before you hand-pick intervals for the real dashboard.
• Adaptive dashboards. Widgets that render “whatever this filter matches” cannot know the right unit in advance — a bucket-count target keeps the chart readable at any zoom level.
• Varying retention windows. The same query over “last hour” and “last year” (a date filter plus this agg) rescales from minutes to quarters without per-page interval logic.

Parameters for auto_date_histogram #

• field
  (Required, string) Date field you wish to aggregate.
• buckets
  (Optional, integer, default: 10) Target number of buckets. The ladder rounds up to a coarser unit, so the result often carries fewer buckets than requested.
• minimum_interval
  (Optional, string) Smallest interval the picker may choose. Accepted for compatibility; the engine does not currently enforce a floor.
• format / time_zone
  (Optional, string) Accepted for compatibility; keys are epoch milliseconds and boundaries are computed in UTC.

Related #

• date_histogram — you name the interval explicitly, including calendar units.
• histogram — the numeric-field counterpart.
• composite — paginated date_histogram dimension when the bucket count must be bounded page by page.