Variable width histogram aggregation #

A multi-bucket aggregation like histogram, but bucket edges adapt to the data so each bucket holds roughly the same number of documents. Fixed grids go blind where data is sparse and waste resolution where it is dense; the variable-width form spends its buckets where the documents actually are.

How it works #

The engine collects every numeric value, sorts it, and partitions the sorted run into buckets contiguous segments such that the sum of squared distances to each segment’s mean is minimal — the classic one-dimensional k-segmentation problem, solved exactly with dynamic programming and prefix sums (an O(1) cost function per candidate cut). When n × k exceeds 1,048,576 it falls back to equal-count chunking, a linear-time approximation. buckets is capped at the number of distinct values, so asking for more buckets than there are values simply yields one bucket per value.

Each bucket reports doc_count and a key object with three fields: min and max (the bucket’s data extent) and key (their midpoint). Buckets are returned in ascending order — dense regions come back as narrow [min, max] windows, sparse tails as wide ones.

Example #

The teaching prices take only four distinct values (15/30/45/60), so four buckets means one value per bucket: 60/30/20/10 documents behind min = max edges. Ask for two buckets instead and the optimal split runs [15, 30] with 90 sales against [45, 60] with 30 — the edge moves to where the mass divides, not to a fixed grid line.

Use cases #

• Equi-populous report rows. “Top decile”, “quintile”, “the 1%” are statements about counts, not value widths — k segments over sorted data is exactly that grouping, with the bucket min/max reporting each band’s actual edges.
• Skewed numeric fields. Latency, income, view counts: a fixed interval either smears the bulk into one bucket or shreds the tail into thousands. Adaptive edges keep every bucket informative.
• Pre-histogram reconnaissance. Run it before a histogram to see where the mass sits, then fix the interval where it matters.
• Compact distribution summaries. Feed the min/max/doc_count triples straight into a heat strip or a box-style rendering.

Parameters for variable_width_histogram #

• field
  (Required, string) Numeric field you wish to aggregate.
• buckets
  (Optional, integer, default: 10) Target number of buckets; capped at the number of distinct values.
• aggs
  (Optional, object) Nested sub-aggregations, computed per bucket.

Related #

• histogram — fixed-width buckets when the grid itself must be stable across queries.
• percentiles — quantile cut points without committing to a bucket count.
• auto_date_histogram — the same “target a bucket count” idea over date fields.