Elasticsearch Match Query: Full-Text Search Syntax and Examples - Syntax, Example, and Tips

The Elasticsearch match query is the standard full-text query. It runs the input through the field's analyzer to produce tokens, then constructs a boolean query over those tokens against the inverted index. It works on text fields (and on keyword, numeric, date, and boolean fields when an exact value is supplied). Use match whenever the user-typed query should be tokenized, lowercased, or stemmed before being compared against the index.

Syntax

{
  "query": {
    "match": {
      "<field>": {
        "query":                "<text>",
        "operator":             "or",
        "minimum_should_match": "75%",
        "fuzziness":            "AUTO",
        "prefix_length":        0,
        "max_expansions":       50,
        "zero_terms_query":     "none",
        "analyzer":             "<custom_analyzer>",
        "lenient":              false,
        "auto_generate_synonyms_phrase_query": true
      }
    }
  }
}

Shorthand form when only query is needed: { "match": { "field": "text" } }.

Parameters

Examples

Simple full-text match:

GET /articles/_search
{
  "query": { "match": { "body": "distributed search" } }
}

All tokens required (AND operator):

GET /articles/_search
{
  "query": {
    "match": {
      "body": { "query": "distributed search engine", "operator": "and" }
    }
  }
}

Tolerate typos with fuzziness:

GET /articles/_search
{
  "query": {
    "match": {
      "title": { "query": "elastcsearch", "fuzziness": "AUTO" }
    }
  }
}

Partial match threshold via minimum_should_match:

GET /articles/_search
{
  "query": {
    "match": {
      "body": { "query": "kafka topic partition replica", "minimum_should_match": "75%" }
    }
  }
}

Performance and Use Notes

match runs the field's search_analyzer (falling back to its analyzer) on the input, so query behavior follows field mapping. A field analyzed with standard lowercases and removes most punctuation; with english, it also stems - so "running" matches "run". Mismatch between the index-time and query-time analyzer is the most common cause of "match query returns nothing" tickets.

match does not preserve word order. To require an exact phrase, use the match_phrase query. For querying multiple fields with one input, use multi_match. For the same text against text and keyword subfields with combined scoring, multi_match with type: best_fields or cross_fields is usually a better fit than several match clauses inside bool.should.

Inefficient match queries with fuzziness or large max_expansions can saturate clusters under load. Pulse detects expensive match queries on your Elasticsearch cluster, flags analyzer/mapping mismatches, and recommends rewrites - typically moving fuzziness off the hot path or replacing free-form match with structured filters.

Common Mistakes

1. Using match on a keyword field expecting partial matching - keyword fields are not analyzed, so the whole input is the single token.
2. Forgetting that english and similar stemming analyzers fold plurals; match: "categories" and match: "category" match the same documents.
3. Setting operator: and on long queries and getting empty results because not every token exists in any document.
4. Combining fuzziness with a 1-character query - the AUTO rule produces no edits at length 1-2, so fuzziness has no effect.
5. Relying on match for exact-value filtering instead of term; when score is irrelevant the term query in a filter is faster and cacheable.

Frequently Asked Questions

Q: What is the difference between the match query and the term query in Elasticsearch?
A: The match query analyzes the input through the field's analyzer before searching the inverted index, so "Running" matches "run" on an English-analyzed field. The term query does not analyze and compares the raw input byte-for-byte; it is the right choice for keyword, numeric, date, and boolean fields.

Q: How does the operator parameter affect a match query?
A: With or (default), any analyzed token can match. With and, every token produced by the analyzer must be present. minimum_should_match is the finer-grained alternative for partial-match thresholds.

Q: How does fuzziness work in the match query?
A: fuzziness uses Levenshtein edit distance over individual tokens. AUTO is 0 for ≤2-char terms, 1 for 3-5 chars, and 2 for ≥6 chars. prefix_length reduces cost by requiring the leading characters to match exactly; max_expansions caps the number of fuzzy term variants enumerated.

Q: Why does my match query return no results even though the words appear in documents?
A: Most often the index-time analyzer and the query input do not produce overlapping tokens. Use the _analyze API to inspect what the field actually indexes, and compare to what the query analyzer produces from the input.

Q: Can I use the match query on numeric or date fields?
A: Yes - Elasticsearch will parse the input into the field's type. For ranges, use the range query; for exact numeric or date equality, the term query is more explicit.

Q: How do I search across multiple fields with a single match query?
A: The match query targets one field. Use multi_match (with type: best_fields, most_fields, or cross_fields) to query several fields with the same input.

Related Reading

• Elasticsearch Term Query: non-analyzed exact-value query.
• Elasticsearch Match Phrase Query: match with word-order preservation.
• Elasticsearch Fuzzy Query: direct fuzziness on a single term.
• Elasticsearch Bool Query: combine match clauses with must/should/filter.
• Elasticsearch Simple Query String Query: user-facing query parser over multiple fields.