Improve top_metrics docs (#53521) (#53619)

* Removes experimental.
* Replaces `"v"` (for value) with `"m"` (for metric).
* Move the note about tiebreaking into the list of limitations of the
  sort.
* Explain how you ask for `metrics`.
* Clean up some wording.
* Link to the docs from `top_metrics`.

Closes #51813

Author: nik9000

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-body-search-sort, search>> request except:
 * It can't be used on <<binary,binary>>, <<flattened,flattened>, <<ip,ip>>,
 <<keyword,keyword>>, or <<text,text>> 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
-<<search-aggregations-metrics-top-metrics-example-terms, terms aggregation>>.
+<<search-aggregations-metrics-top-metrics-example-terms, terms aggregation>>. 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 } } ]
     }
   }
 }

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
 * <<request-body-search-version,Include versions>>
 * <<request-body-search-seq-no-primary-term,Include Sequence Numbers and Primary Terms>>
 
+IMPORTANT: If you *only* need `docvalue_fields`, `size`, and `sort` then
+<<search-aggregations-metrics-top-metrics>> 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.