Support value retrieval in top_hits (#95828)

This is used when the `top_hits` output is passed to pipeline
aggregators like bucket selectors. The logic retrieves the requested
field from the source of the first SearchHit. This implies that (a) the
spec of the wrapping aggregator (e.g. `bucket_path`) points to an
appropriate field using a bracketed reference (e.g.
`my_top_hits[my_metric]`) and (b) the `top_hits` contains a `size: 1`
setting.

This PR also includes extensions to YAML tests for `top_metrics` and
`top_hits` to cover the cases where these are used in pipeline
aggregations through `bucket_selector`, similar to a HAVING clause in
SQL.

Related to #73429.

Author: kkrik-es

docs/changelog/95828.yaml

@@ -0,0 +1,5 @@
+pr: 95828
+summary: Support value retrieval in `top_hits`
+area: Aggregations
+type: enhancement
+issues: []

docs/reference/aggregations/metrics/top-metrics-aggregation.asciidoc

@@ -416,3 +416,44 @@ Which returns the much more expected:
 }
 ----
 // TESTRESPONSE
+
+===== Use in pipeline aggregations
+
+`top_metrics` can be used in pipeline aggregations that consume a single value per bucket, such as `bucket_selector`
+that applies per bucket filtering, similar to using a HAVING clause in SQL. This requires setting `size` to 1, and
+specifying the right path for the (single) metric to be passed to the wrapping aggregator. For example:
+
+[source,console]
+----
+POST /test*/_search?filter_path=aggregations
+{
+  "aggs": {
+    "ip": {
+      "terms": {
+        "field": "ip"
+      },
+      "aggs": {
+        "tm": {
+          "top_metrics": {
+            "metrics": {"field": "m"},
+            "sort": {"s": "desc"},
+            "size": 1
+          }
+        },
+        "having_tm": {
+          "bucket_selector": {
+            "buckets_path": {
+              "top_m": "tm[m]"
+            },
+            "script": "params.top_m < 1000"
+          }
+        }
+      }
+    }
+  }
+}
+----
+// TEST[continued]
+
+The `bucket_path` uses the `top_metrics` name `tm` and a keyword for the metric providing the aggregate value,
+namely `m`.

docs/reference/aggregations/metrics/tophits-aggregation.asciidoc

@@ -415,3 +415,56 @@ the second slow of the `nested_child_field` field:
 ...
 --------------------------------------------------
 // NOTCONSOLE
+
+==== Use in pipeline aggregations
+
+`top_hits` can be used in pipeline aggregations that consume a single value per bucket, such as `bucket_selector`
+that applies per bucket filtering, similar to using a HAVING clause in SQL. This requires setting `size` to 1, and
+specifying the right path for the value to be passed to the wrapping aggregator. The latter can be a `_source`, a
+`_sort` or a `_score` value. For example:
+
+[source,console]
+--------------------------------------------------
+POST /sales/_search?size=0
+{
+  "aggs": {
+    "top_tags": {
+      "terms": {
+        "field": "type",
+        "size": 3
+      },
+      "aggs": {
+        "top_sales_hits": {
+          "top_hits": {
+            "sort": [
+              {
+                "date": {
+                  "order": "desc"
+                }
+              }
+            ],
+            "_source": {
+              "includes": [ "date", "price" ]
+            },
+            "size": 1
+          }
+        },
+        "having.top_salary": {
+          "bucket_selector": {
+            "buckets_path": {
+              "tp": "top_sales_hits[_source.price]"
+            },
+            "script": "params.tp < 180"
+          }
+        }
+      }
+    }
+  }
+}
+
+--------------------------------------------------
+// TEST[setup:sales]
+
+The `bucket_path` uses the `top_hits` name `top_sales_hits` and a keyword for the field providing the aggregate value,
+namely `_source` field `price` in the example above. Other options include `top_sales_hits[_sort]`, for filtering on the
+sort value `date` above, and `top_sales_hits[_score]`, for filtering on the score of the top hit.