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:

GET _search
{
  "query": {
    "match": {
      "title": "wind"
    }
  }
}

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

GET _search
{
  "query": {
    "match": {
      "title": {
        "query": "wind",
        "analyzer": "stop"
      }
    }
  }
}

Examples

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

PUT testindex/_doc/1
{
  "title": "Let the wind rise"
}

PUT testindex/_doc/2
{
  "title": "Gone with the wind"
  
}

PUT testindex/_doc/3
{
  "title": "Rise is gone"
}

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:

GET testindex/_search
{
  "query": {
    "match": {
      "title": {
        "query": "wind rise",
        "operator": "and"
      }
    }
  }
}

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

{
  "took": 17,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 1.2667098,
    "hits": [
      {
        "_index": "testindex",
        "_id": "1",
        "_score": 1.2667098,
        "_source": {
          "title": "Let the wind rise"
        }
      }
    ]
  }
}

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:

GET testindex/_search
{
  "query": {
    "match": {
      "title": {
        "query": "wind rise",
        "operator": "or",
        "minimum_should_match": 2
      }
    }
  }
}

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

{
  "took": 23,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 1.2667098,
    "hits": [
      {
        "_index": "testindex",
        "_id": "1",
        "_score": 1.2667098,
        "_source": {
          "title": "Let the wind rise"
        }
      }
    ]
  }
}

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:

GET testindex/_search
{
  "query": {
    "match": {
      "title": {
        "query": "the wind rises",
        "operator": "and",
        "analyzer": "english"
      }
    }
  }
}

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:

{
  "took": 19,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 1.2667098,
    "hits": [
      {
        "_index": "testindex",
        "_id": "1",
        "_score": 1.2667098,
        "_source": {
          "title": "Let the wind rise"
        }
      }
    ]
  }
}

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:

GET testindex/_analyze
{
  "analyzer" : "english",
  "text" : "and OR or"
}

As expected, the query produces no tokens:

{
  "tokens": []
}

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:

GET testindex/_search
{
  "query": {
    "match": {
      "title": {
        "query": "and OR or",
        "analyzer" : "english",
        "zero_terms_query": "all"
      }
    }
  }
}

Fuzziness

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

• An integer that specifies the maximum allowed 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:

GET testindex/_search
{
  "query": {
    "match": {
      "title": {
        "query": "wnid",
        "fuzziness": "AUTO"
      }
    }
  }
}

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

{
  "took": 31,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 2,
      "relation": "eq"
    },
    "max_score": 0.47501624,
    "hits": [
      {
        "_index": "testindex",
        "_id": "1",
        "_score": 0.47501624,
        "_source": {
          "title": "Let the wind rise"
        }
      },
      {
        "_index": "testindex",
        "_id": "2",
        "_score": 0.47501624,
        "_source": {
          "title": "Gone with the wind"
        }
      }
    ]
  }
}

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:

GET testindex/_search
{
  "query": {
    "match": {
      "title": {
        "query": "wnid",
        "fuzziness": "AUTO",
        "prefix_length": 2
      }
    }
  }
}

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:

GET testindex/_search
{
  "query": {
    "match": {
      "title": {
        "query": "wnid",
        "fuzziness": "AUTO",
        "fuzzy_transpositions": false
      }
    }
  }
}

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:

GET /testindex/_search
{
  "query": {
    "match": {
      "text": {
        "query": "good ba",
        "auto_generate_synonyms_phrase_query": false
      }
    }
  }
}

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

Parameters

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

GET _search
{
  "query": {
    "match": {
      "<field>": {
        "query": "text to search for",
        ... 
      }
    }
  }
}

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