Add WeightedAvg metric aggregation #31037
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,185 @@ | ||
| [[search-aggregations-metrics-weight-avg-aggregation]] | ||
| === Weighted Avg Aggregation | ||
|
|
||
| A `single-value` metrics aggregation that computes the weighted average of numeric values that are extracted from the aggregated documents. | ||
| These values can be extracted either from specific numeric fields in the documents. | ||
|
|
||
| When calculating a regular average, each datapoint has an equal "weight" ... it contributes equally to the final value. Weighted averages, | ||
| on the other hand, weight each datapoint differently. The amount that each datapoint contributes to the final value is extracted from the | ||
| document, or provided by a script. | ||
|
|
||
| As a formula, a weighted average is the `∑(value * weight) / ∑(weight)` | ||
|
|
||
| A regular average can be thought of as a weighted average where every value has an implicit weight of `1`. | ||
|
|
||
|
|
||
| .`weighted_avg` Parameters | ||
| |=== | ||
| |Parameter Name |Description |Required |Default Value | ||
| |`value` | The configuration for the field or script that provides the values |Required | | ||
| |`weight` | The configuration for the field or script that provides the weights |Required | | ||
| |`format` | The numeric response formatter |Optional | | ||
| |`value_type` | A hint about the values for pure scripts or unmapped fields |Optional | | ||
| |=== | ||
|
|
||
| The `value` and `weight` objects have per-field specific configuration: | ||
|
|
||
| .`value` Parameters | ||
| |=== | ||
| |Parameter Name |Description |Required |Default Value | ||
| |`field` | The field that values should be extracted from |Required | | ||
| |`missing` | A value to use if the field is missing entirely |Optional | | ||
| |`multi` | If a document has multiple values for the field, how should the values be combined |Optional | `avg` | ||
| |`script` | A script which provides the values for the document. This is mutually exclusive with `field` |Optional | ||
| |=== | ||
|
|
||
| .`weight` Parameters | ||
| |=== | ||
| |Parameter Name |Description |Required |Default Value | ||
| |`field` | The field that weights should be extracted from |Required | | ||
| |`missing` | A weight to use if the field is missing entirely |Optional | | ||
| |`multi` | If a document has multiple values for the field, how should the values be combined |Optional | `avg` | ||
| |`script` | A script which provides the values for the document. This is mutually exclusive with `field` |Optional | ||
|
||
| |=== | ||
|
|
||
|
|
||
| ==== Examples | ||
|
|
||
| If our documents have a `"grade"` field that holds a 0-100 numeric score, and a `"weight"` field which holds an arbitrary numeric weight, | ||
| we can calculate the weighted average using: | ||
|
|
||
| [source,js] | ||
| -------------------------------------------------- | ||
| POST /exams/_search | ||
| { | ||
| "size": 0, | ||
| "aggs" : { | ||
| "weighted_grade": { | ||
| "weighted_avg": { | ||
| "value": { | ||
| "field": "grade" | ||
| }, | ||
| "weight": { | ||
| "field": "weight" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| -------------------------------------------------- | ||
| // CONSOLE | ||
| // TEST[setup:exams] | ||
|
|
||
| Which yields a response like: | ||
|
|
||
| [source,js] | ||
| -------------------------------------------------- | ||
| { | ||
| ... | ||
| "aggregations": { | ||
| "weighted_grade": { | ||
| "value": 70.0 | ||
| } | ||
| } | ||
| } | ||
| -------------------------------------------------- | ||
| // TESTRESPONSE[s/\.\.\./"took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits,/] | ||
|
|
||
|
|
||
| ==== Script | ||
|
|
||
| Both the value and the weight can be derived from a script, instead of a field. As a simple example, the following | ||
| will add one to the grade and weight in the document using a script: | ||
|
|
||
| [source,js] | ||
| -------------------------------------------------- | ||
| POST /exams/_search | ||
| { | ||
| "size": 0, | ||
| "aggs" : { | ||
| "weighted_grade": { | ||
| "weighted_avg": { | ||
| "value": { | ||
| "script": "doc.grade.value + 1" | ||
| }, | ||
| "weight": { | ||
| "script": "doc.weight.value + 1" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| -------------------------------------------------- | ||
| // CONSOLE | ||
| // TEST[setup:exams] | ||
|
|
||
|
|
||
| ==== Missing values | ||
|
|
||
| The `missing` parameter defines how documents that are missing a value should be treated. | ||
| The default behavior is different for `value` and `weight`: | ||
|
|
||
| By default, if the `value` field is missing the document is ignored and the aggregation moves on to the next document. | ||
| If the `weight` field is missing, it is assumed to have a weight of `1` (like a normal average). | ||
|
|
||
| Both of these defaults can be overridden with the `missing` parameter: | ||
|
|
||
| [source,js] | ||
| -------------------------------------------------- | ||
| POST /exams/_search | ||
| { | ||
| "size": 0, | ||
| "aggs" : { | ||
| "weighted_grade": { | ||
| "weighted_avg": { | ||
| "value": { | ||
| "field": "grade", | ||
| "missing": 2 | ||
| }, | ||
| "weight": { | ||
| "field": "weight", | ||
| "missing": 3 | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| -------------------------------------------------- | ||
| // CONSOLE | ||
| // TEST[setup:exams] | ||
|
|
||
| ==== Multi-value mode | ||
|
|
||
| If a document has multiple values, you can configure the `multi` mode of both `value` and `weight`. This controls | ||
| how the multiple values should be combined when calculating the average. Acceptable values are: | ||
|
|
||
| - `avg`: average the multiple values together | ||
| - `min`: use the minimum value | ||
| - `max`: use the maximum value | ||
| - `sum`: sum all the values together | ||
|
|
||
| The default if unspecified is `avg`. | ||
|
|
||
| [source,js] | ||
| -------------------------------------------------- | ||
| POST /exams/_search | ||
| { | ||
| "size": 0, | ||
| "aggs" : { | ||
| "weighted_grade": { | ||
| "weighted_avg": { | ||
| "value": { | ||
| "field": "grade", | ||
| "multi": "avg" | ||
| }, | ||
| "weight": { | ||
| "field": "weight", | ||
| "multi": "min" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| -------------------------------------------------- | ||
| // CONSOLE | ||
| // TEST[setup:exams] | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should this say
weightsinstead ofvalues?