How to Use multi_match Query in Elasticsearch: Syntax and Examples

Use the multi_match query in Elasticsearch to search for a text across multiple fields in your documents. It allows specifying the fields and the search text in one query, making it easy to find matches in several fields at once.

Syntax

The multi_match query has these main parts:

• query: The text you want to search for.
• fields: An array of fields where Elasticsearch will look for the query text.
• type (optional): Defines how the query matches, like best_fields or most_fields.

json

{
  "query": {
    "multi_match": {
      "query": "search text",
      "fields": ["field1", "field2", "field3"],
      "type": "best_fields"
    }
  }
}

Example

This example searches for the phrase quick brown fox in the fields title and description. It uses the default best_fields type, which finds the best matching field.

json

{
  "query": {
    "multi_match": {
      "query": "quick brown fox",
      "fields": ["title", "description"]
    }
  }
}

Output

{
  "hits": {
    "total": {
      "value": 2,
      "relation": "eq"
    },
    "hits": [
      {
        "_source": {
          "title": "The quick brown fox",
          "description": "A fast fox jumps over the lazy dog"
        }
      },
      {
        "_source": {
          "title": "Fox stories",
          "description": "A quick brown fox tale"
        }
      }
    ]
  }
}

Common Pitfalls

Common mistakes when using multi_match include:

• Not specifying the fields array, which causes the query to fail.
• Using fields that are not analyzed for text search, resulting in no matches.
• Confusing multi_match with match which only searches one field.

Always check your field mappings to ensure they support full-text search.

json

{
  "query": {
    "multi_match": {
      "query": "example",
      "fields": []  
    }
  }
}

// Correct usage:
{
  "query": {
    "multi_match": {
      "query": "example",
      "fields": ["title", "content"]
    }
  }
}

Quick Reference

Parameter	Description	Default/Options
query	The text to search for	Required
fields	List of fields to search	Required
type	How to combine matches	best_fields (default), most_fields, cross_fields, phrase, phrase_prefix
operator	Logical operator between terms	or (default), and
minimum_should_match	Minimum number of terms to match	Optional

Key Takeaways

Use multi_match to search multiple fields with one query in Elasticsearch.

Always specify the fields array to tell Elasticsearch where to search.

Choose the type option to control how matches across fields are combined.

Check that your fields support full-text search to avoid empty results.

Avoid empty or missing fields to prevent query errors.