OpenSearch/docs/reference/migration/migrate_5_0/percolator.asciidoc

[[breaking_50_percolator]]
=== Percolator changes

==== Percolator is near-real time

Previously percolators were activated in real-time, i.e. as soon as they were
indexed.  Now, changes to the percolator query are visible in near-real time,
as soon as the index has been refreshed. This change was required because, in
indices created from 5.0 onwards, the terms used in a percolator query are
automatically indexed to allow for more efficient query selection during
percolation.

==== Percolate and multi percolator APIs

Percolator and multi percolate APIs have been deprecated and will be removed in the next major release. These APIs have
been replaced by the `percolator` query that can be used in the search and multi search APIs.

==== Percolator mapping

The `percolator` query  can no longer accept documents that reference fields
that don't already exist in the mapping. Before the percolate API allowed this.

The `percolator` query no longer modifies the mappings. Before the percolate API
could be used to dynamically introduce new fields to the mappings based on the
fields in the document being percolated. This no longer works, because these
unmapped fields are not persisted in the mapping.

==== Percolator documents returned by search

Documents with the `.percolate` type were previously excluded from the search
response, unless the `.percolate` type was specified explicitly in the search
request.  Now, percolator documents are treated in the same way as any other
document and are returned by search requests.

==== Percolating existing document

When percolating an existing document then also specifying a document as source in the
`percolator` query is not allowed any more. Before the percolate API allowed and ignored
the existing document.

==== Percolate Stats

Percolate stats have been replaced with percolator query cache stats in nodes stats and cluster stats APIs.