Weighted average aggregation #

A single-value metrics aggregation that computes the weighted average of numeric values. Each document contributes value × weight, divided by the total weight — e.g. an average price weighted by quantity sold. When documents are not all equally important, avg is the wrong tool and this is the right one.

How it works #

The engine walks the matching documents once, accumulating Σ(value × weight) in the numerator and Σ weight in the denominator; the result is their quotient. Both sides are computed in the same pass over two columns, so the pairing of a document’s value with its own weight is never lost.

A document contributes only when both sides resolve: a missing value is substituted with value.missing if given, a missing weight with weight.missing — otherwise the document is dropped entirely, from the numerator and the denominator. Weights of 0 contribute nothing to either side; when the total weight is not positive, the result is null.

value and weight each take a field (scripts are rejected here — use a scripted avg or scripted_metric for computed sources).

Distributed requests carry a caveat: the finalized {"value": …} shape discards the two sums, so the coordinator cannot combine shard results exactly and falls back to the arithmetic mean of the per-shard means. On the teaching single-shard datasets the result is exact; on multi-shard deployments treat the number as an approximation.

Example #

Average unit price weighted by qty (larger purchases count more):

The plain avg of price is 27.5; quantity-weighted it is 28.125.

Use cases #

• True average unit price. Weight price by qty over the 120 sales: 28.125 — exactly sum(amount) / sum(qty) (6750 / 240), the number finance means by “average price actually sold at”.
• Inventory value per unit. products averages 15.43 on price, but 15.87 when weighted by stock — the stockroom skews toward pricier items, a gap plain avg hides.
• Why the two diverge. In the teaching data qty is positively correlated with price (sticker sales average 3 units, t-shirts 2), so heavier weights sit on higher values and drag the weighted mean above the plain one; when weights correlate with the value, the gap is the signal.
• Partial-data tolerance. Sparse weight fields don’t corrupt the mean: documents without a weight drop out of both sums via weight.missing, so an unlogged quantity shrinks the denominator honestly instead of counting as zero.
• Blended metrics. Any score-times-importance blend — engagement time weighted by session count, rating weighted by review count — is this aggregation with two field names.

Parameters for weighted_avg #

• value
  (Required, object) field — the numeric field whose values are averaged.
• weight
  (Required, object) field — the numeric field used as the per-document weight.
• value.missing / weight.missing
  (Optional, number) Value substituted for documents missing the field; a missing weight defaults the document out of the average.

Related #

• avg — the unweighted mean over the same field
• sum — the numerator without the division
• stats — count/min/max/avg/sum for context around either mean
• scripted_metric — computed value or weight sources