Bucket sort aggregation #

A parent pipeline aggregation sorting (and paginating) the bucket list by any of the bucket’s metrics — the pipeline counterpart of the request-level sort.

"by_revenue": {
  "bucket_sort": { "sort": [ { "revenue": { "order": "asc" } } ] }
}

How it works #

Status, verified against the engine: bucket_sort is accepted but not yet active. The request parses — sort, from and size are accepted — but no reordering or truncation is applied: the parent aggregation’s buckets come back in the parent’s own order. A declared bucket_sort evaluates to a null metric, and nested declarations currently leave a "by_revenue": { "value": null } placeholder in each bucket (unlike bucket_selector, it does not clean up after itself).

What is available today for the same goals:

• Cap the bucket count — the bucket aggregation’s own size (terms, rare_terms, …) limits how many buckets are produced in the first place (default 10).
• Filter buckets by metric — bucket_selector keeps exactly the buckets whose script predicate passes.
• Find the extremes — max_bucket / min_bucket extract the top or bottom bucket as a single value.
• Sort client-side — until the pipeline lands, reorder the returned buckets in your application.

When the implementation lands, requests written today are already the right shape: sort clauses over any per-bucket metric (or _key / _count), then from skipped, then at most size kept.

Examples #

The request runs and answers; in the current engine the four type buckets arrive in the terms order (t-shirt, hat, mug, sticker, by document count) rather than by ascending revenue — the intended order would be mug (1350) before the three 1800s.

Use cases #

What bucket_sort is for once active — and the working substitute for each today:

• Top-N by metric — best-selling categories first: use bucket_selector with a threshold, or max_bucket for the single best.
• Pagination of buckets — from/size windows over a long bucket list: use the bucket aggregation’s size for a hard cap.
• Consistent display order — a dashboard that always wants worst-first buckets: sort the returned array client-side for now.

Parameters for bucket_sort #

• sort
  (Optional, array) Sort clauses over the bucket’s metrics ([{ "revenue": { "order": "desc" } }]). Accepted; not yet applied.
• from
  (Optional, integer) Skip this many buckets — pagination offset. Accepted; not yet applied.
• size
  (Optional, integer) Keep at most this many buckets. Accepted; not yet applied.
• gap_policy
  (Optional, string) skip (default) or insert_zeros.

Related #

• bucket_selector — metric-based bucket filtering that works today
• bucket_script — derive the metric you want to sort by
• max_bucket, min_bucket — extract the extreme bucket now
• terms — size on the bucket aggregation itself