Multi Match Query

The multi_match query builds on the match query to allow multi-field queries:

GET /_search
{
  "query": {
    "multi_match" : {
      "query":    "this is a test", 
      "fields": [ "subject", "message" ] 
    }
  }
}

Where:

• query: The query string
• fields: The fields to be queried. Fields can be specified as wildcards

Example

The following example would query title, first_name and last_name

GET /_search
{
  "query": {
    "multi_match" : {
      "query":    "Will Smith",
      "fields": [ "title", "*_name" ] 
    }
  }
}

Individual fields can be boosted with the caret (^) notation. In the following query the subject field is three times as important as the message field.

GET /_search
{
  "query": {
    "multi_match" : {
      "query" : "this is a test",
      "fields" : [ "subject^3", "message" ] 
    }
  }
}

Types of multi_match query

The way the multi_match query is executed internally depends on the type parameter, which can be set to:

• best_fields: (default) Finds documents which match any field, but uses the _score from the best field. See best_fields.

• most_fields: Finds documents which match any field and combines the _score from each field. See most_fields.

• cross_fields: Treats fields with the same analyser as though they were one big field. Looks for each word in any field. See cross_fields.

• phrase: Runs a match_phrase query on each field and combines the _score from each field. See phrase and phrase_prefix.

• phrase_prefix: Runs a match_phrase_prefix query on each field and combines the _score from each field. See phrase and phrase_prefix.

best_fields

The best_fields type is most useful when you are searching for multiple words best found in the same field. For instance “brown fox” in a single field is more meaningful than “brown” in one field and “fox” in the other.

The best_fields type generates a match query for each field and wraps them in a dis_max query, to find the single best matching field. For instance, this query:

GET /_search
{
  "query": {
    "multi_match" : {
      "query":      "brown fox",
      "type":       "best_fields",
      "fields":     [ "subject", "message" ],
      "tie_breaker": 0.3
    }
  }
}

Normally the best_fields type uses the score of the single best matching field, but if tie_breaker is specified, then it calculates the score as follows:

• the score from the best matching field
• plus tie_breaker * _score for all other matching fields

Also, accepts analyser, boost, operator, minimum_should_match, fuzziness, lenient, prefix_length, max_expansions, rewrite, zero_terms_query and cutoff_frequency, as explained in match query.

most_fields

The most_fields type is most useful when querying multiple fields that contain the same text analyzed in different ways. For instance, the main field may contain synonyms, stemming and terms without diacritics. A second field may contain the original terms, and a third field might contain shingles. By combining scores from all three fields we can match as many documents as possible with the main field, but use the second and third fields to push the most similar results to the top of the list.

This query:

GET /_search
{
  "query": {
    "multi_match" : {
      "query":      "quick brown fox",
      "type":       "most_fields",
      "fields":     [ "title", "title.original", "title.shingles" ]
    }
  }
}

The score from each match clause is added together, then divided by the number of match clauses.

Also, accepts analyzer, boost, operator, minimum_should_match, fuzziness, lenient, prefix_length, max_expansions, rewrite, zero_terms_query and cutoff_frequency, as explained in match query, but see operator and minimum_should_match.

phrase and phrase_prefix

The phrase and phrase_prefix types behave just like best_fields, but they use a match_phrase or match_phrase_prefix query instead of a match query.

This query:

GET /_search
{
  "query": {
    "multi_match" : {
      "query":      "quick brown f",
      "type":       "phrase_prefix",
      "fields":     [ "subject", "message" ]
    }
  }
}

Also, accepts analyzer, boost, lenient, slop and zero_terms_query as explained in Match Query. Type phrase_prefix additionally accepts max_expansions.

Note: The fuzziness parameter cannot be used with the phrase or phrase_prefix type.

cross_fields

The cross_fields type is particularly useful with structured documents where multiple fields should match. For instance, when querying the first_name and last_name fields for “Will Smith”, the best match is likely to have “Will” in one field and “Smith” in the other.

Note: This sounds like a job for most_fields but there are two problems with that approach. The first problem is that operator and minimum_should_match are applied per-field, instead of per-term (see explanation above).

The second problem is to do with relevance: the different term frequencies in the first_name and last_name fields can produce unexpected results.

For instance, imagine we have two people: “Will Smith” and “Smith Jones”. “Smith” as a last name is very common (and so is of low importance) but “Smith” as a first name is very uncommon (and so is of great importance).

If we do a search for “Will Smith”, the “Smith Jones” document will probably appear above the better matching “Will Smith” because the score of first_name:smith has trumped the combined scores of first_name:will plus last_name:smith.