Support value retrieval in top_hits

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.