Match query

Use the match query for full-text search on a specific document field. If you run a match query on a text field, the match query analyzes the provided search string and returns documents that match any of the string’s terms. If you run a match query on an exact-value field, it returns documents that match the exact value. The preferred way to search exact-value fields is to use a filter because, unlike a query, a filter is cached.

The following example shows a basic match query for the word wind in the title:

  1. GET _search
  2. {
  3.   "query": {
  4.     "match": {
  5.       "title": "wind"
  6.     }
  7.   }
  8. }

copy

To pass additional parameters, you can use the expanded syntax:

  1. GET _search
  2. {
  3.   "query": {
  4.     "match": {
  5.       "title": {
  6.         "query": "wind",
  7.         "analyzer": "stop"
  8.       }
  9.     }
  10.   }
  11. }

copy

Examples

In the following examples, you’ll use the index that contains the following documents:

  1. PUT testindex/_doc/1
  2. {
  3.   "title": "Let the wind rise"
  4. }

copy

  1. PUT testindex/_doc/2
  2. {
  3.   "title": "Gone with the wind"
  5. }

copy

  1. PUT testindex/_doc/3
  2. {
  3.   "title": "Rise is gone"
  4. }

copy

Operator

If a match query is run on a text field, the text is analyzed with the analyzer specified in the analyzer parameter. Then the resulting tokens are combined into a Boolean query using the operator specified in the operator parameter. The default operator is OR, so the query wind rise is changed into wind OR rise. In this example, this query returns documents 1–3 because each document has a term that matches the query. To specify the and operator, use the following query:

  1. GET testindex/_search
  2. {
  3.   "query": {
  4.     "match": {
  5.       "title": {
  6.         "query": "wind rise",
  7.         "operator": "and"
  8.       }
  9.     }
  10.   }
  11. }

copy

The query is constructed as wind AND rise and returns document 1 as the matching document:

Response

  1. {
  2.   "took": 17,
  3.   "timed_out": false,
  4.   "_shards": {
  5.     "total": 1,
  6.     "successful": 1,
  7.     "skipped": 0,
  8.     "failed": 0
  9.   },
  10.   "hits": {
  11.     "total": {
  12.       "value": 1,
  13.       "relation": "eq"
  14.     },
  15.     "max_score": 1.2667098,
  16.     "hits": [
  17.       {
  18.         "_index": "testindex",
  19.         "_id": "1",
  20.         "_score": 1.2667098,
  21.         "_source": {
  22.           "title": "Let the wind rise"
  23.         }
  24.       }
  25.     ]
  26.   }
  27. }

Minimum should match

You can control the minimum number of terms that a document must match to be returned in the results by specifying the minimum_should_match parameter:

  1. GET testindex/_search
  2. {
  3.   "query": {
  4.     "match": {
  5.       "title": {
  6.         "query": "wind rise",
  7.         "operator": "or",
  8.         "minimum_should_match": 2
  9.       }
  10.     }
  11.   }
  12. }

copy

Now documents are required to match both terms, so only document 1 is returned (this is equivalent to the and operator):

Response

  1. {
  2.   "took": 23,
  3.   "timed_out": false,
  4.   "_shards": {
  5.     "total": 1,
  6.     "successful": 1,
  7.     "skipped": 0,
  8.     "failed": 0
  9.   },
  10.   "hits": {
  11.     "total": {
  12.       "value": 1,
  13.       "relation": "eq"
  14.     },
  15.     "max_score": 1.2667098,
  16.     "hits": [
  17.       {
  18.         "_index": "testindex",
  19.         "_id": "1",
  20.         "_score": 1.2667098,
  21.         "_source": {
  22.           "title": "Let the wind rise"
  23.         }
  24.       }
  25.     ]
  26.   }
  27. }

Analyzer

Because in this example you didn’t explicitly specify the analyzer, the default standard analyzer is used. The default analyzer does not perform stemming, so if you run a query the wind rises, you receive no results because the token rises does not match the token rise. To change the search analyzer, specify it in the analyzer field. For example, the following query uses the english analyzer:

  1. GET testindex/_search
  2. {
  3.   "query": {
  4.     "match": {
  5.       "title": {
  6.         "query": "the wind rises",
  7.         "operator": "and",
  8.         "analyzer": "english"
  9.       }
  10.     }
  11.   }
  12. }

copy

The english analyzer removes the stopword the and performs stemming, producing the tokens wind and rise. The latter token matches document 1, which is returned in the results:

Response

  1. {
  2.   "took": 19,
  3.   "timed_out": false,
  4.   "_shards": {
  5.     "total": 1,
  6.     "successful": 1,
  7.     "skipped": 0,
  8.     "failed": 0
  9.   },
  10.   "hits": {
  11.     "total": {
  12.       "value": 1,
  13.       "relation": "eq"
  14.     },
  15.     "max_score": 1.2667098,
  16.     "hits": [
  17.       {
  18.         "_index": "testindex",
  19.         "_id": "1",
  20.         "_score": 1.2667098,
  21.         "_source": {
  22.           "title": "Let the wind rise"
  23.         }
  24.       }
  25.     ]
  26.   }
  27. }

Empty query

In some cases, an analyzer might remove all tokens from a query. For example, the english analyzer removes stop words, so in a query and OR or, all tokens are removed. To check the analyzer behavior, you can use the Analyze API:

  1. GET testindex/_analyze
  2. {
  3.   "analyzer" : "english",
  4.   "text" : "and OR or"
  5. }

copy

As expected, the query produces no tokens:

  1. {
  2.   "tokens": []
  3. }

You can specify the behavior for an empty query in the zero_terms_query parameter. Setting zero_terms_query to all returns all documents in the index and setting it to none returns no documents:

  1. GET testindex/_search
  2. {
  3.   "query": {
  4.     "match": {
  5.       "title": {
  6.         "query": "and OR or",
  7.         "analyzer" : "english",
  8.         "zero_terms_query": "all"
  9.       }
  10.     }
  11.   }
  12. }

copy

Fuzziness

To account for typos, you can specify fuzziness for your query as either of the following:

  • An integer that specifies the maximum allowed Damerau–Levenshtein distance for this edit.
  • AUTO:
    • Strings of 0–2 characters must match exactly.
    • Strings of 3–5 characters allow 1 edit.
    • Strings longer than 5 characters allow 2 edits.

Setting fuzziness to the default AUTO value works best in most cases:

  1. GET testindex/_search
  2. {
  3.   "query": {
  4.     "match": {
  5.       "title": {
  6.         "query": "wnid",
  7.         "fuzziness": "AUTO"
  8.       }
  9.     }
  10.   }
  11. }

copy

The token wnid matches wind and the query returns documents 1 and 2:

Response

  1. {
  2.   "took": 31,
  3.   "timed_out": false,
  4.   "_shards": {
  5.     "total": 1,
  6.     "successful": 1,
  7.     "skipped": 0,
  8.     "failed": 0
  9.   },
  10.   "hits": {
  11.     "total": {
  12.       "value": 2,
  13.       "relation": "eq"
  14.     },
  15.     "max_score": 0.47501624,
  16.     "hits": [
  17.       {
  18.         "_index": "testindex",
  19.         "_id": "1",
  20.         "_score": 0.47501624,
  21.         "_source": {
  22.           "title": "Let the wind rise"
  23.         }
  24.       },
  25.       {
  26.         "_index": "testindex",
  27.         "_id": "2",
  28.         "_score": 0.47501624,
  29.         "_source": {
  30.           "title": "Gone with the wind"
  31.         }
  32.       }
  33.     ]
  34.   }
  35. }

Prefix length

Misspellings rarely occur in the beginning of words. Thus, you can specify the minimum length the matched prefix must be to return a document in the results. For example, you can change the preceding query to include a prefix_length:

  1. GET testindex/_search
  2. {
  3.   "query": {
  4.     "match": {
  5.       "title": {
  6.         "query": "wnid",
  7.         "fuzziness": "AUTO",
  8.         "prefix_length": 2
  9.       }
  10.     }
  11.   }
  12. }

copy

The preceding query returns no results. If you change the prefix_length to 1, documents 1 and 2 are returned because the first letter of the token wnid is not misspelled.

Transpositions

In the preceding example, the word wnid contained a transposition (in was changed to ni). By default, transpositions are allowed in fuzzy matching, but you can disallow them by setting fuzzy_transpositions to false:

  1. GET testindex/_search
  2. {
  3.   "query": {
  4.     "match": {
  5.       "title": {
  6.         "query": "wnid",
  7.         "fuzziness": "AUTO",
  8.         "fuzzy_transpositions": false
  9.       }
  10.     }
  11.   }
  12. }

copy

Now the query returns no results.

Synonyms

If you use a synonym_graph filter and auto_generate_synonyms_phrase_query is set to true (default), OpenSearch parses the query into terms and then combines the terms to generate a phrase query for multi-term synonyms. For example, if you specify ba,batting average as synonyms and search for ba, OpenSearch searches for ba OR "batting average".

To match multi-term synonyms with conjunctions, set auto_generate_synonyms_phrase_query to false:

  1. GET /testindex/_search
  2. {
  3.   "query": {
  4.     "match": {
  5.       "text": {
  6.         "query": "good ba",
  7.         "auto_generate_synonyms_phrase_query": false
  8.       }
  9.     }
  10.   }
  11. }

copy

The query produced is ba OR (batting AND average).

Parameters

The query accepts the name of the field (<field>) as a top-level parameter:

  1. GET _search
  2. {
  3.   "query": {
  4.     "match": {
  5.       "<field>": {
  6.         "query": "text to search for",
  7.         ... 
  8.       }
  9.     }
  10.   }
  11. }

copy

The <field> accepts the following parameters. All parameters except query are optional.

ParameterData typeDescription
queryStringThe query string to use for search. Required.
autogenerate_synonyms_phrase_queryBooleanSpecifies whether to create a match phrase query automatically for multi-term synonyms. For example, if you specify ba,batting average as synonyms and search for ba, OpenSearch searches for ba OR “batting average” (if this option is true) or ba OR (batting AND average) (if this option is false). Default is true.
analyzerStringThe analyzer used to tokenize the query string text. Default is the index-time analyzer specified for the default_field. If no analyzer is specified for the default_field, the analyzer is the default analyzer for the index.
boostFloating-pointBoosts the clause by the given multiplier. Useful for weighing clauses in compound queries. Values in the [0, 1) range decrease relevance, and values greater than 1 increase relevance. Default is 1.
enable_position_incrementsBooleanWhen true, resulting queries are aware of position increments. This setting is useful when the removal of stop words leaves an unwanted “gap” between terms. Default is true.
fuzzinessStringThe number of character edits (insertions, deletions, substitutions, or transpositions) that it takes to change one word to another when determining whether a term matched a value. For example, the distance between wined and wind is 1. Valid values are non-negative integers or AUTO. The default, AUTO, chooses a value based on the length of each term and is a good choice for most use cases.
fuzzy_rewriteStringDetermines how OpenSearch rewrites the query. Valid values are constant_score, scoring_boolean, constant_score_boolean, top_terms_N, top_terms_boost_N, and top_terms_blended_freqs_N. If the fuzziness parameter is not 0, the query uses a fuzzy_rewrite method of top_terms_blended_freqs${max_expansions} by default. Default is constant_score.
fuzzy_transpositionsBooleanSetting fuzzy_transpositions to true (default) adds swaps of adjacent characters to the insert, delete, and substitute operations of the fuzziness option. For example, the distance between wind and wnid is 1 if fuzzy_transpositions is true (swap “n” and “i”) and 2 if it is false (delete “n”, insert “n”). If fuzzy_transpositions is false, rewind and wnid have the same distance (2) from wind, despite the more human-centric opinion that wnid is an obvious typo. The default is a good choice for most use cases.
lenientBooleanSetting lenient to true ignores data type mismatches between the query and the document field. For example, a query string of “8.2” could match a field of type float. Default is false.
max_expansionsPositive integerThe 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.
minimum_should_matchPositive or negative integer, positive or negative percentage, combinationIf the query string contains multiple search terms and you use the or operator, the number of terms that need to match for the document to be considered a match. For example, if minimum_should_match is 2, wind often rising does not match The Wind Rises. If minimum_should_match is 1, it matches. For details, see Minimum should match.
operatorStringIf the query string contains multiple search terms, whether all terms need to match (AND) or only one term needs to match (OR) for a document to be considered a match. Valid values are:
- OR: The string to be is interpreted as to OR be
- AND: The string to be is interpreted as to AND be
Default is OR.
prefix_lengthNon-negative integerThe number of leading characters that are not considered in fuzziness. Default is 0.
zero_terms_queryStringIn some cases, the analyzer removes all terms from a query string. For example, the stop analyzer removes all terms from the string an but this. In those cases, zero_terms_query specifies whether to match no documents (none) or all documents (all). Valid values are none and all. Default is none.