From 06d31591257234ba578bf74fef6f9430efed48eb Mon Sep 17 00:00:00 2001
From: James Rodewig <40268737+jrodewig@users.noreply.github.com>
Date: Mon, 17 Aug 2020 13:05:40 -0400
Subject: [PATCH] [DOCS] Add usage tips to `top_hits` agg (#61215) (#61225)

---
 .../aggregations/metrics/tophits-aggregation.asciidoc    | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/docs/reference/aggregations/metrics/tophits-aggregation.asciidoc b/docs/reference/aggregations/metrics/tophits-aggregation.asciidoc
index 1f6dff1395a..6e4f7ba2c2c 100644
--- a/docs/reference/aggregations/metrics/tophits-aggregation.asciidoc
+++ b/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.