elasticsearch/docs/reference/migration/migrate_5_0/suggest.asciidoc

[[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": [ {...} ]
}
---------------