You're viewing version 2.13 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.
Fuzzy query
A fuzzy query searches for documents containing terms that are similar to the search term within the maximum allowed Levenshtein distance. The Levenshtein distance measures the number of one-character changes needed to change one term to another term. These changes include:
- Replacements: cat to bat
- Insertions: cat to cats
- Deletions: cat to at
- Transpositions: cat to act
A fuzzy query creates a list of all possible expansions of the search term that fall within the Levenshtein distance. You can specify the maximum number of such expansions in the max_expansions
field. Then it searches for documents that match any of the expansions.
The following example query searches for the speaker HALET
(misspelled HAMLET
). The maximum edit distance is not specified, so the default AUTO
edit distance is used:
GET shakespeare/_search
{
"query": {
"fuzzy": {
"speaker": {
"value": "HALET"
}
}
}
}
The response contains all documents in which HAMLET
is the speaker.
The following example query searches for the word HALET
with advanced parameters:
GET shakespeare/_search
{
"query": {
"fuzzy": {
"speaker": {
"value": "HALET",
"fuzziness": "2",
"max_expansions": 40,
"prefix_length": 0,
"transpositions": true,
"rewrite": "constant_score"
}
}
}
}
Parameters
The query accepts the name of the field (<field>
) as a top-level parameter:
GET _search
{
"query": {
"fuzzy": {
"<field>": {
"value": "sample",
...
}
}
}
}
The <field>
accepts the following parameters. All parameters except value
are optional.
Parameter | Data type | Description |
---|---|---|
value | String | The term to search for in the field specified in <field> . |
boost | Floating-point | A floating-point value that specifies the weight of this field toward the relevance score. Values above 1.0 increase the field’s relevance. Values between 0.0 and 1.0 decrease the field’s relevance. Default is 1.0. |
fuzziness | AUTO , 0 , or a positive integer | The number of character edits (insert, delete, substitute) needed to change one word to another when determining whether a term matched a value. For example, the distance between wined and wind is 1. The default, AUTO , chooses a value based on the length of each term and is a good choice for most use cases. |
max_expansions | Positive integer | The maximum number of terms to which the query can expand. Fuzzy queries “expand to” a number of matching terms that are within the distance specified in fuzziness . Then OpenSearch tries to match those terms. Default is 50 . |
prefix_length | Non-negative integer | The number of leading characters that are not considered in fuzziness. Default is 0 . |
rewrite | String | Determines how OpenSearch rewrites and scores multi-term queries. Valid values are constant_score , scoring_boolean , constant_score_boolean , top_terms_N , top_terms_boost_N , and top_terms_blended_freqs_N . Default is constant_score . |
transpositions | Boolean | Specifies whether to allow transpositions of two adjacent characters (ab to ba ) as edits. Default is true . |
Specifying a large value in max_expansions
can lead to poor performance, especially if prefix_length
is set to 0
, because of the large number of variations of the word that OpenSearch tries to match.
If search.allow_expensive_queries
is set to false
, fuzzy queries are not run.