Merge pull request #20169 from areek/doc/fix_completion_breaking_changes

Update breaking changes for completion suggester

docs/reference/migration/migrate_5_0/suggest.asciidoc

@@ -3,7 +3,8 @@
 
 The completion suggester has undergone a complete rewrite. This means that the
 syntax and data structure for fields of type `completion` have changed, as
-have the syntax and response of completion suggester requests.
+have the syntax and response of completion suggester requests. See
+<<search-suggesters-completion,completion suggester>> for details.
 
 For indices created before Elasticsearch 5.0.0, `completion` fields and the
 completion suggester will continue to work as they did in Elasticsearch 2.x.
@@ -25,35 +26,17 @@ to suggestion entries for both context and completion suggesters.
 
 ==== Completion suggester is document-oriented
 
-Suggestions are aware of the document they belong to. This enables
-retrieving any field value from the document. This is exposed
-through the query-time `payload` option in `completion` and `context`
-suggesters:
+Suggestions are aware of the document they belong to. Now, associated
+documents (`_source`) are returned as part of `completion` suggestions.
 
-[source,sh]
----------------
-GET /my_index/_search
-{
-  "suggest": {
-    "fooSuggestion": {
-       "text": "f"
-       "completion": {
-         "field": "fooSuggest",
-         "payload": ["field1", "field2"]
-       }
-     }
-  }
-}
----------------
+IMPORTANT: `_source` meta-field must be enabled, which is the default behavior,
+to enable returning `_source` with suggestions.
 
 Previously, `context` and `completion` suggesters supported an index-time
 `payloads` option, which was used to store and return metadata with suggestions.
-Now metadata can be stored as a field in the same document as the
-suggestion for enabling retrieval at query-time. The support for
-index-time `payloads` has been removed to avoid bloating the in-memory
-index with suggestion metadata. The time that it takes to retrieve payloads
-depends heavily on the size of the `_source` field.  The smaller the `_source`,
-the faster the retrieval.
+Now metadata can be stored as part of the the same document as the
+suggestion for retrieval at query-time. The support for index-time `payloads`
+has been removed to avoid bloating the in-memory index with suggestion metadata.
 
 ==== Simpler completion indexing
 

docs/reference/search/suggesters/completion-suggest.asciidoc

@@ -194,26 +194,50 @@ returns this response:
 --------------------------------------------------
 // TESTRESPONSE
 
-The configured weight for a suggestion is returned as `_score`.
-The `text` field uses the `input` of your indexed suggestion.
-Suggestions are document oriented, the document source is
-returned in `_source`. <<search-request-source-filtering, source filtering>>
-parameters are supported for filtering the document source.
+
+IMPORTANT: `_source` meta-field must be enabled, which is the default
+behavior, to enable returning `_source` with suggestions.
+
+The configured weight for a suggestion is returned as `_score`. The
+`text` field uses the `input` of your indexed suggestion. Suggestions
+return the full document `_source` by default. The size of the `_source`
+can impact performance due to disk fetch and network transport overhead.
+For best performance, filter out unnecessary fields from the `_source`
+using <<search-request-source-filtering, source filtering>> to minimize
+`_source` size. The following demonstrates an example completion query
+with source filtering:
+
+[source,js]
+--------------------------------------------------
+POST music/_suggest
+{
+    "_source": "completion.*",
+    "song-suggest" : {
+        "prefix" : "nir",
+        "completion" : {
+            "field" : "suggest"
+        }
+    }
+}
+--------------------------------------------------
 
 The basic completion suggester query supports the following parameters:
 
 `field`:: The name of the field on which to run the query (required).
 `size`::  The number of suggestions to return (defaults to `5`).
-`payload`::  The name of the field or field name array to be returned
-             as payload (defaults to no fields).
 
 NOTE: The completion suggester considers all documents in the index.
 See <<suggester-context>> for an explanation of how to query a subset of
 documents instead.
 
-NOTE: Specifying `payload` fields will incur additional search performance
-hit. The `payload` fields are retrieved eagerly (single pass) for top
-suggestions at the shard level using field data or from doc values.
+NOTE: In case of completion queries spanning more than one shard, the suggest
+is executed in two phases, where the last phase fetches the relevant documents
+from shards, implying executing completion requests against a single shard is
+more performant due to the document fetch overhead when the suggest spans
+multiple shards. To get best performance for completions, it is recommended to
+index completions into a single shard index. In case of high heap usage due to
+shard size, it is still recommended to break index into multiple shards instead
+of optimizing for completion performance.
 
 [[fuzzy]]
 ==== Fuzzy queries