Browse Source

[DOCS] Add usage tips to `top_hits` agg (#61215)

James Rodewig 5 years ago
parent
commit
456c37b186
1 changed files with 9 additions and 0 deletions
  1. 9 0
      docs/reference/aggregations/metrics/tophits-aggregation.asciidoc

+ 9 - 0
docs/reference/aggregations/metrics/tophits-aggregation.asciidoc

@@ -4,6 +4,10 @@
 A `top_hits` metric aggregator keeps track of the most relevant document being aggregated. This aggregator is intended
 to be used as a sub aggregator, so that the top matching documents can be aggregated per bucket.
 
+TIP: We do not recommend using `top_hits` as a top-level aggregation. If you
+want to group search hits, use the <<collapse-search-results,`collapse`>>
+parameter instead.
+
 The `top_hits` aggregator can effectively be used to group result sets by certain fields via a bucket aggregator.
 One or more bucket aggregators determines by which properties a result set get sliced into.
 
@@ -30,6 +34,11 @@ 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
 <<search-aggregations-metrics-top-metrics>> might be a more efficient choice than the Top Hits Aggregation.
 
+`top_hits` does not support the <<rescore,`rescore`>> parameter. Query rescoring
+applies only to search hits, not aggregation results. To change the scores used
+by aggregations, use a <<query-dsl-function-score-query,`function_score`>> or
+<<query-dsl-script-score-query,`script_score`>> query.
+
 ==== Example
 
 In the following example we group the sales by type and per type we show the last sale.