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. 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.
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. Now, associated
documents (`_source`) are returned as part of `completion` suggestions.

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 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

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