From c869ca18ebc4ecfda3eb8e63adbc354600934b55 Mon Sep 17 00:00:00 2001
From: Areek Zillur <areek.zillur@elasticsearch.com>
Date: Thu, 25 Aug 2016 15:42:55 -0400
Subject: [PATCH] Update breaking changes for completion suggester

To indicate we removed completion payload option
in favour of returning document source with
completion suggestions
---
 .../migration/migrate_5_0/suggest.asciidoc    | 61 +++++++++++--------
 1 file changed, 36 insertions(+), 25 deletions(-)

diff --git a/docs/reference/migration/migrate_5_0/suggest.asciidoc b/docs/reference/migration/migrate_5_0/suggest.asciidoc
index 0b67711fe00..822dcd45700 100644
--- a/docs/reference/migration/migrate_5_0/suggest.asciidoc
+++ b/docs/reference/migration/migrate_5_0/suggest.asciidoc
@@ -25,35 +25,46 @@ 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"]
-       }
-     }
-  }
-}
----------------
+WARNING: `_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.
+
+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.
+
+Completion results 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"
+        }
+    }
+}
+--------------------------------------------------
 
 ==== Simpler completion indexing