Normalize aggregation #

A parent pipeline aggregation rescaling a bucket metric into a share or rank — e.g. each bucket’s revenue as a percent of the total (percent_of_sum), a 0..1 position (rescale_0_1), or standard deviations from the mean (z-score).

"share": {
  "normalize": { "buckets_path": "per_type>revenue", "method": "percent_of_sum" }
}

How it works #

In this engine normalize is evaluated in the sibling placement: declare it next to the bucket aggregation and point buckets_path at the series with the full parent>metric form. The engine collects one value per bucket, applies the chosen method across the whole series, and emits a standalone buckets array (keys 0..n−1) with one value per consumed bucket.

The methods, verified against the engine:

Any other method string passes the original values through unchanged rather than failing the request. Buckets whose metric is missing are skipped — there is no gap_policy parameter.

The nested declaration (normalize inside the terms agg’s aggs, bare buckets_path) parses but is not wired to the nested injection path yet: every bucket’s entry stays null. Use the sibling form above.

Examples #

The four product types earn 1800, 1800, 1350, 1800 (of 6750 total), so share.buckets answers 26.67, 26.67, 20.0, 26.67 — percentages that sum to exactly 100 and line up, by position, with per_type.buckets.

Use cases #

• Share of total — percent_of_sum turns per-category revenue into composition: “mug is 20% of sales” survives any change in overall volume a raw total does not.
• Comparable scales — rescale_0_1 puts series measured in different units (orders, revenue, defects) on one 0..1 axis for side-by-side sparklines.
• Outlier ranking — z-score expresses each bucket in standard deviations from its own mean: sort by it and the anomalous buckets surface regardless of their raw scale.
• Attention-style weights — softmax converts the series into positive weights summing to 1, e.g. to allocate quota or traffic proportionally to per-bucket scores.
• Centering before further math — mean subtracts the series mean, the standard first step before variance-based analysis.

Parameters for normalize #

• buckets_path
  (Required, string) Path to the consumed series: "<bucket_agg>><metric>".
• method
  (Required, string) One of percent_of_sum, rescale_0_1, rescale_0_100, mean, z-score, softmax; any other value passes values through unchanged.

Related #

• avg_bucket — the mean of the same series in one number
• bucket_script — arbitrary per-bucket arithmetic when a fixed method is not enough
• percentiles_bucket — rank within the series