diff --git a/docs/reference/aggregations/metrics/top-metrics-aggregation.asciidoc b/docs/reference/aggregations/metrics/top-metrics-aggregation.asciidoc index 5958d09f4ed71..6dbc8adfd3ff8 100644 --- a/docs/reference/aggregations/metrics/top-metrics-aggregation.asciidoc +++ b/docs/reference/aggregations/metrics/top-metrics-aggregation.asciidoc @@ -3,26 +3,24 @@ [[search-aggregations-metrics-top-metrics]] === Top Metrics Aggregation -experimental[We expect to change the response format of this aggregation as we add more features., https://github.com/elastic/elasticsearch/issues/51813] - The `top_metrics` aggregation selects metrics from the document with the largest or smallest "sort" -value. For example, This gets the value of the `v` field on the document with the largest value of `s`: +value. For example, this gets the value of the `m` field on the document with the largest value of `s`: [source,console,id=search-aggregations-metrics-top-metrics-simple] ---- POST /test/_bulk?refresh {"index": {}} -{"s": 1, "v": 3.1415} +{"s": 1, "m": 3.1415} {"index": {}} -{"s": 2, "v": 1.0} +{"s": 2, "m": 1.0} {"index": {}} -{"s": 3, "v": 2.71828} +{"s": 3, "m": 2.71828} POST /test/_search?filter_path=aggregations { "aggs": { "tm": { "top_metrics": { - "metrics": {"field": "v"}, + "metrics": {"field": "m"}, "sort": {"s": "desc"} } } @@ -37,7 +35,7 @@ Which returns: { "aggregations": { "tm": { - "top": [ {"sort": [3], "metrics": {"v": 2.718280076980591 } } ] + "top": [ {"sort": [3], "metrics": {"m": 2.718280076980591 } } ] } } } @@ -54,7 +52,7 @@ The `sort` field in the metric request functions exactly the same as the `sort` <> request except: * It can't be used on <>, <, <>, <>, or <> fields. -* It only supports a single sort value. +* It only supports a single sort value so which document wins ties is not specified. The metrics that the aggregation returns is the first hit that would be returned by the search request. So, @@ -65,14 +63,12 @@ request. So, gets metrics from the documents with `location` *closest* to `35.7796, -78.6382` `"sort": "_score"`:: gets metrics from the document with the highest score -NOTE: This aggregation doesn't support any sort of "tie breaking". If two documents have -the same sort values then this aggregation could return either document's fields. - ==== `metrics` -`metrics` selects the fields to of the "top" document to return. - -You can return multiple metrics by providing a list: +`metrics` selects the fields to of the "top" document to return. You can return +a request a single metric with something like `"metric": {"field": "m"}` or multiple +metrics by requesting a list of metrics like `"metric": [{"field": "m"}, {"field": "i"}`. +Here is a more complete example: [source,console,id=search-aggregations-metrics-top-metrics-list-of-metrics] ---- @@ -86,19 +82,19 @@ PUT /test } POST /test/_bulk?refresh {"index": {}} -{"s": 1, "v": 3.1415, "m": 1, "d": "2020-01-01T00:12:12Z"} +{"s": 1, "m": 3.1415, "i": 1, "d": "2020-01-01T00:12:12Z"} {"index": {}} -{"s": 2, "v": 1.0, "m": 6, "d": "2020-01-02T00:12:12Z"} +{"s": 2, "m": 1.0, "i": 6, "d": "2020-01-02T00:12:12Z"} {"index": {}} -{"s": 3, "v": 2.71828, "m": -12, "d": "2019-12-31T00:12:12Z"} +{"s": 3, "m": 2.71828, "i": -12, "d": "2019-12-31T00:12:12Z"} POST /test/_search?filter_path=aggregations { "aggs": { "tm": { "top_metrics": { "metrics": [ - {"field": "v"}, {"field": "m"}, + {"field": "i"}, {"field": "d"} ], "sort": {"s": "desc"} @@ -118,8 +114,8 @@ Which returns: "top": [ { "sort": [3], "metrics": { - "v": 2.718280076980591, - "m": -12, + "m": 2.718280076980591, + "i": -12, "d": "2019-12-31T00:12:12.000Z" } } ] @@ -137,19 +133,19 @@ Which returns: ---- POST /test/_bulk?refresh {"index": {}} -{"s": 1, "v": 3.1415} +{"s": 1, "m": 3.1415} {"index": {}} -{"s": 2, "v": 1.0} +{"s": 2, "m": 1.0} {"index": {}} -{"s": 3, "v": 2.71828} +{"s": 3, "m": 2.71828} POST /test/_search?filter_path=aggregations { "aggs": { "tm": { "top_metrics": { - "metrics": {"field": "v"}, + "metrics": {"field": "m"}, "sort": {"s": "desc"}, - "size": 2 + "size": 3 } } } @@ -164,8 +160,9 @@ Which returns: "aggregations": { "tm": { "top": [ - {"sort": [3], "metrics": {"v": 2.718280076980591 } }, - {"sort": [2], "metrics": {"v": 1.0 } } + {"sort": [3], "metrics": {"m": 2.718280076980591 } }, + {"sort": [2], "metrics": {"m": 1.0 } }, + {"sort": [1], "metrics": {"m": 3.1414999961853027 } } ] } } @@ -179,7 +176,8 @@ is a *very* conservative default maximum and you can raise it if you need to by changing the `top_metrics_max_size` index setting. But know that large sizes can take a fair bit of memory, especially if they are inside of an aggregation which makes many buckes like a large -<>. +<>. If +you till want to raise it, use something like: [source,console] ---- @@ -190,8 +188,7 @@ PUT /test/_settings ---- // TEST[continued] -NOTE: If `size` is more than `1` the `top_metrics` aggregation can't be the target of a sort. - +NOTE: If `size` is more than `1` the `top_metrics` aggregation can't be the *target* of a sort. ==== Examples @@ -214,11 +211,11 @@ PUT /node } POST /node/_bulk?refresh {"index": {}} -{"ip": "192.168.0.1", "date": "2020-01-01T01:01:01", "v": 1} +{"ip": "192.168.0.1", "date": "2020-01-01T01:01:01", "m": 1} {"index": {}} -{"ip": "192.168.0.1", "date": "2020-01-01T02:01:01", "v": 2} +{"ip": "192.168.0.1", "date": "2020-01-01T02:01:01", "m": 2} {"index": {}} -{"ip": "192.168.0.2", "date": "2020-01-01T02:01:01", "v": 3} +{"ip": "192.168.0.2", "date": "2020-01-01T02:01:01", "m": 3} POST /node/_search?filter_path=aggregations { "aggs": { @@ -229,7 +226,7 @@ POST /node/_search?filter_path=aggregations "aggs": { "tm": { "top_metrics": { - "metrics": {"field": "v"}, + "metrics": {"field": "m"}, "sort": {"date": "desc"} } } @@ -251,14 +248,14 @@ Which returns: "key": "192.168.0.1", "doc_count": 2, "tm": { - "top": [ {"sort": ["2020-01-01T02:01:01.000Z"], "metrics": {"v": 2 } } ] + "top": [ {"sort": ["2020-01-01T02:01:01.000Z"], "metrics": {"m": 2 } } ] } }, { "key": "192.168.0.2", "doc_count": 1, "tm": { - "top": [ {"sort": ["2020-01-01T02:01:01.000Z"], "metrics": {"v": 3 } } ] + "top": [ {"sort": ["2020-01-01T02:01:01.000Z"], "metrics": {"m": 3 } } ] } } ], @@ -280,12 +277,12 @@ POST /node/_search?filter_path=aggregations "ip": { "terms": { "field": "ip", - "order": {"tm.v": "desc"} + "order": {"tm.m": "desc"} }, "aggs": { "tm": { "top_metrics": { - "metrics": {"field": "v"}, + "metrics": {"field": "m"}, "sort": {"date": "desc"} } } @@ -308,14 +305,14 @@ Which returns: "key": "192.168.0.2", "doc_count": 1, "tm": { - "top": [ {"sort": ["2020-01-01T02:01:01.000Z"], "metrics": {"v": 3 } } ] + "top": [ {"sort": ["2020-01-01T02:01:01.000Z"], "metrics": {"m": 3 } } ] } }, { "key": "192.168.0.1", "doc_count": 2, "tm": { - "top": [ {"sort": ["2020-01-01T02:01:01.000Z"], "metrics": {"v": 2 } } ] + "top": [ {"sort": ["2020-01-01T02:01:01.000Z"], "metrics": {"m": 2 } } ] } } ], @@ -337,17 +334,17 @@ always sorted independantly of whole numbered fields. ---- POST /test/_bulk?refresh {"index": {"_index": "test1"}} -{"s": 1, "v": 3.1415} +{"s": 1, "m": 3.1415} {"index": {"_index": "test1"}} -{"s": 2, "v": 1} +{"s": 2, "m": 1} {"index": {"_index": "test2"}} -{"s": 3.1, "v": 2.71828} +{"s": 3.1, "m": 2.71828} POST /test*/_search?filter_path=aggregations { "aggs": { "tm": { "top_metrics": { - "metrics": {"field": "v"}, + "metrics": {"field": "m"}, "sort": {"s": "asc"} } } @@ -362,7 +359,7 @@ Which returns: { "aggregations": { "tm": { - "top": [ {"sort": [3.0999999046325684], "metrics": {"v": 2.718280076980591 } } ] + "top": [ {"sort": [3.0999999046325684], "metrics": {"m": 2.718280076980591 } } ] } } } @@ -380,7 +377,7 @@ POST /test*/_search?filter_path=aggregations "aggs": { "tm": { "top_metrics": { - "metrics": {"field": "v"}, + "metrics": {"field": "m"}, "sort": {"s": {"order": "asc", "numeric_type": "double"}} } } @@ -396,7 +393,7 @@ Which returns the much more expected: { "aggregations": { "tm": { - "top": [ {"sort": [1.0], "metrics": {"v": 3.1414999961853027 } } ] + "top": [ {"sort": [1.0], "metrics": {"m": 3.1414999961853027 } } ] } } } diff --git a/docs/reference/aggregations/metrics/tophits-aggregation.asciidoc b/docs/reference/aggregations/metrics/tophits-aggregation.asciidoc index 1f43a038e7c17..117d0e249c197 100644 --- a/docs/reference/aggregations/metrics/tophits-aggregation.asciidoc +++ b/docs/reference/aggregations/metrics/tophits-aggregation.asciidoc @@ -27,6 +27,9 @@ The top_hits aggregation returns regular search hits, because of this many per h * <> * <> +IMPORTANT: If you *only* need `docvalue_fields`, `size`, and `sort` then +<> might be a more efficient choice than the Top Hits Aggregation. + ==== Example In the following example we group the sales by type and per type we show the last sale.