Document completion suggest breaking changes

docs/reference/migration/migrate_5_0.asciidoc

@@ -32,6 +32,7 @@ way to do this is to upgrade to Elasticsearch 2.3 or later and to use the
 * <<breaking_50_search_changes>>
 * <<breaking_50_mapping_changes>>
 * <<breaking_50_percolator>>
+* <<breaking_50_suggester>>
 * <<breaking_50_index_apis>>
 * <<breaking_50_settings_changes>>
 * <<breaking_50_allocation>>
@@ -51,6 +52,8 @@ include::migrate_5_0/mapping.asciidoc[]
 
 include::migrate_5_0/percolator.asciidoc[]
 
+include::migrate_5_0/suggest.asciidoc[]
+
 include::migrate_5_0/index-apis.asciidoc[]
 
 include::migrate_5_0/settings.asciidoc[]

docs/reference/migration/migrate_5_0/suggest.asciidoc

@@ -0,0 +1,91 @@
+[[breaking_50_suggester]]
+=== Suggester changes
+
+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.
+
+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.
+However, it is not possible to run a completion suggester query across indices
+created in 2.x and indices created in 5.x.
+
+It is strongly recommended to reindex indices containing 2.x `completion`
+fields in 5.x to take advantage of the new features listed below.
+
+NOTE: You will need to change the structure of the completion field values
+when reindexing.
+
+==== Completion suggester is near-real time
+
+Previously, deleted suggestions could be included in results even
+after refreshing an index. Now, deletions are visible in near-real
+time, i.e. as soon as the index has been refreshed. This applies
+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:
+
+[source,sh]
+---------------
+GET /my_index/_search
+{
+  "suggest": {
+    "fooSuggestion": {
+       "text": "f"
+       "completion": {
+         "field": "fooSuggest",
+         "payload": ["field1", "field2"]
+       }
+     }
+  }
+}
+---------------
+
+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.
+
+==== Simpler completion indexing
+
+As suggestions are document-oriented, suggestion metadata (e.g. `output`)
+should now be specified as a field in the document. The support for specifying
+`output` when indexing suggestion entries has been removed. Now suggestion
+result entry's `text` is always the un-analyzed value of the suggestion's
+`input` (same as not specifying `output` while indexing suggestions in pre-5.0
+indices).
+
+==== Completion mapping with multiple contexts
+
+The `context` option in `completion` field mapping is now an array to support
+multiple named contexts per completion field. Note that this is sugar for
+indexing same suggestions under different name with different contexts.
+The `default` option for a named `context` has been removed. Now querying with
+no `context` against a context-enabled completion field yields results from all
+indexed suggestions. Note that performance for match-all-context query
+degrades with the number of unique context value for a given `completion` field.
+
+==== Completion suggestion with multiple context filtering
+
+Previously `context` option in a suggest request was used for filtering suggestions
+by `context` value. Now, the option has been named to `contexts` to specify
+multiple named context filters. Note that this is not supported by pre-5.0 indices.
+Following is the `contexts` snippet for a suggest query filtered by both 'color'
+and 'location' contexts:
+
+[source,sh]
+---------------
+"contexts": {
+  "color": [ {...} ],
+  "location": [ {...} ]
+}
+---------------