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", 1
      "fields": [ "subject", "message" ] 2
    }
  }
}

1. The query string.
2. The fields to be queried.

Fields can be specified with wildcards, eg:

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

1. Query the title, first_name and last_name fields.

Individual fields can be boosted with the caret (^) notation:

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

1. The query multiplies the subject field’s score by three but leaves the message field’s score unchanged.

If no fields are provided, the multi_match query defaults to the index.query.default_field index settings, which in turn defaults to *. * extracts all fields in the mapping that are eligible to term queries and filters the metadata fields. All extracted fields are then combined to build a 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 analyzer 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 uses the _score from the best field. See phrase and phrase_prefix.

phrase_prefix

Runs a match_phrase_prefix query on each field and uses the _score from the best field. See phrase and phrase_prefix.

bool_prefix

Creates a match_bool_prefix query on each field and combines the _score from each field. See bool_prefix.

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
    }
  }
}

would be executed as:

 GET /_search {
  "query": {
    "dis_max": {
      "queries": [
        { "match": { "subject": "brown fox" }},
        { "match": { "message": "brown fox" }}
      ],
      "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 analyzer, boost, operator, minimum_should_match, fuzziness, lenient, prefix_length, max_expansions, fuzzy_rewrite, zero_terms_query, auto_generate_synonyms_phrase_query and fuzzy_transpositions, as explained in match query.

 GET /_search {
  "query": {
    "multi_match" : {
      "query":      "Will Smith",
      "type":       "best_fields",
      "fields":     [ "first_name", "last_name" ],
      "operator":   "and" 1
    }
  }
}

  (+first_name:will +first_name:smith)
| (+last_name:will  +last_name:smith)

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" ]
    }
  }
}

would be executed as:

 GET /_search {
  "query": {
    "bool": {
      "should": [
        { "match": { "title":          "quick brown fox" }},
        { "match": { "title.original": "quick brown fox" }},
        { "match": { "title.shingles": "quick brown fox" }}
      ]
    }
  }
}

The score from each match clause is added together, just like a bool query.

Also, accepts analyzer, boost, operator, minimum_should_match, fuzziness, lenient, prefix_length, max_expansions, fuzzy_rewrite, and zero_terms_query.

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" ]
    }
  }
}

would be executed as:

 GET /_search {
  "query": {
    "dis_max": {
      "queries": [
        { "match_phrase_prefix": { "subject": "quick brown f" }},
        { "match_phrase_prefix": { "message": "quick brown f" }}
      ]
    }
  }
}

Also, accepts analyzer, boost, lenient and zero_terms_query as explained in Match, as well as slop which is explained in Match phrase. Type phrase_prefix additionally accepts max_expansions.

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.

One way of dealing with these types of queries is simply to index the first_name and last_name fields into a single full_name field. Of course, this can only be done at index time.

The cross_field type tries to solve these problems at query time by taking a term-centric approach. It first analyzes the query string into individual terms, then looks for each term in any of the fields, as though they were one big field.

A query like:

 GET /_search {
  "query": {
    "multi_match" : {
      "query":      "Will Smith",
      "type":       "cross_fields",
      "fields":     [ "first_name", "last_name" ],
      "operator":   "and"
    }
  }
}

is executed as:

+(first_name:will last_name:will)
+(first_name:smith last_name:smith)

In other words, all terms must be present in at least one field for a document to match. (Compare this to the logic used for best_fields and most_fields.)

That solves one of the two problems. The problem of differing term frequencies is solved by blending the term frequencies for all fields in order to even out the differences.

In practice, first_name:smith will be treated as though it has the same frequencies as last_name:smith, plus one. This will make matches on first_name and last_name have comparable scores, with a tiny advantage for last_name since it is the most likely field that contains smith.

Note that cross_fields is usually only useful on short string fields that all have a boost of 1. Otherwise boosts, term freqs and length normalization contribute to the score in such a way that the blending of term statistics is not meaningful anymore.

If you run the above query through the Validate, it returns this explanation:

+blended("will",  fields: [first_name, last_name])
+blended("smith", fields: [first_name, last_name])

Also, accepts analyzer, boost, operator, minimum_should_match, lenient and zero_terms_query.

The cross_field type can only work in term-centric mode on fields that have the same analyzer. Fields with the same analyzer are grouped together as in the example above. If there are multiple groups, the query will use the best score from any group.

For instance, if we have a first and last field which have the same analyzer, plus a first.edge and last.edge which both use an edge_ngram analyzer, this query:

 GET /_search {
  "query": {
    "multi_match" : {
      "query":      "Jon",
      "type":       "cross_fields",
      "fields":     [
        "first", "first.edge",
        "last",  "last.edge"
      ]
    }
  }
}

would be executed as:

    blended("jon", fields: [first, last])
| (
    blended("j",   fields: [first.edge, last.edge])
    blended("jo",  fields: [first.edge, last.edge])
    blended("jon", fields: [first.edge, last.edge])
)

In other words, first and last would be grouped together and treated as a single field, and first.edge and last.edge would be grouped together and treated as a single field.

Having multiple groups is fine, but when combined with operator or minimum_should_match, it can suffer from the same problem as most_fields or best_fields.

You can easily rewrite this query yourself as two separate cross_fields queries combined with a dis_max query, and apply the minimum_should_match parameter to just one of them:

 GET /_search {
  "query": {
    "dis_max": {
      "queries": [
        {
          "multi_match" : {
            "query":      "Will Smith",
            "type":       "cross_fields",
            "fields":     [ "first", "last" ],
            "minimum_should_match": "50%" 1
          }
        },
        {
          "multi_match" : {
            "query":      "Will Smith",
            "type":       "cross_fields",
            "fields":     [ "*.edge" ]
          }
        }
      ]
    }
  }
}

1. Either will or smith must be present in either of the first or last fields

You can force all fields into the same group by specifying the analyzer parameter in the query.

 GET /_search {
  "query": {
   "multi_match" : {
      "query":      "Jon",
      "type":       "cross_fields",
      "analyzer":   "standard", 1
      "fields":     [ "first", "last", "*.edge" ]
    }
  }
}

1. Use the standard analyzer for all fields.

which will be executed as:

blended("will",  fields: [first, first.edge, last.edge, last])
blended("smith", fields: [first, first.edge, last.edge, last])

By default, each per-term blended query will use the best score returned by any field in a group. Then when combining scores across groups, the query uses the best score from any group. The tie_breaker parameter can change the behavior for both of these steps:

0.0

Take the single best score out of (eg) first_name:will and last_name:will (default)

1.0

Add together the scores for (eg) first_name:will and last_name:will

0.0 < n < 1.0

Take the single best score plus tie_breaker multiplied by each of the scores from other matching fields/ groups

The bool_prefix type’s scoring behaves like most_fields, but using a match_bool_prefix query instead of a match query.

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

The analyzer, boost, operator, minimum_should_match, lenient, zero_terms_query, and auto_generate_synonyms_phrase_query parameters as explained in match query are supported. The fuzziness, prefix_length, max_expansions, fuzzy_rewrite, and fuzzy_transpositions parameters are supported for the terms that are used to construct term queries, but do not have an effect on the prefix query constructed from the final term.

The slop parameter is not supported by this query type.