OpenSearch/docs/reference/query-dsl/fuzzy-query.asciidoc

[[query-dsl-fuzzy-query]]
=== Fuzzy query
++++
<titleabbrev>Fuzzy</titleabbrev>
++++

Returns documents that contain terms similar to the search term, as measured by
a {wikipedia}/Levenshtein_distance[Levenshtein edit distance].

An edit distance is the number of one-character changes needed to turn one term
into another. These changes can include:

* Changing a character (**b**ox → **f**ox)
* Removing a character (**b**lack → lack)
* Inserting a character (sic → sic**k**)
* Transposing two adjacent characters (**ac**t → **ca**t)

To find similar terms, the `fuzzy` query creates a set of all possible
variations, or expansions, of the search term within a specified edit distance.
The query then returns exact matches for each expansion.

[[fuzzy-query-ex-request]]
==== Example requests

[[fuzzy-query-ex-simple]]
===== Simple example

[source,console]
----
GET /_search
{
  "query": {
    "fuzzy": {
      "user.id": {
        "value": "ki"
      }
    }
  }
}
----

[[fuzzy-query-ex-advanced]]
===== Example using advanced parameters

[source,console]
----
GET /_search
{
  "query": {
    "fuzzy": {
      "user.id": {
        "value": "ki",
        "fuzziness": "AUTO",
        "max_expansions": 50,
        "prefix_length": 0,
        "transpositions": true,
        "rewrite": "constant_score"
      }
    }
  }
}
----

[[fuzzy-query-top-level-params]]
==== Top-level parameters for `fuzzy`
`<field>`::
(Required, object) Field you wish to search.

[[fuzzy-query-field-params]]
==== Parameters for `<field>`
`value`::
(Required, string) Term you wish to find in the provided `<field>`.

`fuzziness`::
(Optional, string) Maximum edit distance allowed for matching. See <<fuzziness>>
for valid values and more information.


`max_expansions`::
+
--
(Optional, integer) Maximum number of variations created. Defaults to `50`.

WARNING: Avoid using a high value in the `max_expansions` parameter, especially
if the `prefix_length` parameter value is `0`. High values in the
`max_expansions` parameter can cause poor performance due to the high number of
variations examined.
--

`prefix_length`::
(Optional, integer) Number of beginning characters left unchanged when creating
expansions. Defaults to `0`.

`transpositions`::
(Optional, Boolean) Indicates whether edits include transpositions of two
adjacent characters (ab → ba). Defaults to `true`.

`rewrite`::
(Optional, string) Method used to rewrite the query. For valid values and more
information, see the <<query-dsl-multi-term-rewrite, `rewrite` parameter>>.

[[fuzzy-query-notes]]
==== Notes
Fuzzy queries will not be executed if <<query-dsl-allow-expensive-queries, `search.allow_expensive_queries`>>
is set to false.