Multi-match queries

A multi_match query runs a match query against several fields at once and combines the per-field results into one score. The type parameter controls how the fields are combined.

Use a multi_match query in the following scenarios:

• Searching a title and a body field, where a match in the title should count for more.
• Searching the same text indexed using several analyzers, such as a stemmed and an unstemmed subfield.
• Searching structured data in which one concept is split across fields, such as a first name and a last name.
• Building search-as-you-type experiences across several fields by using the phrase_prefix or bool_prefix type.

Use the ^ operator to boost certain fields. Boosts are multipliers that weigh matches in one field more heavily than matches in other fields. In the following example, a match for “wind” in the title field influences _score four times as much as a match in the plot field:

GET _search
{
  "query": {
    "multi_match": {
      "query": "wind",
      "fields": ["title^4", "plot"]
    }
  }
}

The result is that films like The Wind Rises and Gone with the Wind are near the top of the search results, and films like Twister, which presumably have “wind” in their plot summaries, are near the bottom.

You can use wildcards in the field name. For example, the following query searches the speaker field and all fields that start with play_, for example, play_name or play_title:

GET _search
{
  "query": {
    "multi_match": {
      "query": "hamlet",
      "fields": ["speaker", "play_*"]
    }
  }
}

If you don’t provide the fields parameter, the multi_match query searches the fields specified in the index.query.default_field setting, which defaults to *. The * value selects all fields in the mapping that are eligible for term-level queries, excluding metadata fields, and the query searches all of them.

Each field adds at least one clause to the query, and the total number of clauses is limited by the indices.query.bool.max_clause_count setting, which defaults to 1,024. Searching many fields, either explicitly or by using a wildcard pattern such as *, can exceed this limit.

Multi-match query types

OpenSearch supports the following multi-match query types, which differ in the way the query is executed internally:

• best_fields (default): Returns documents that match any field. Uses the _score of the best-matching field.
• most_fields: Returns documents that match any field. Uses the sum of the scores of all matching fields.
• cross_fields: Treats fields that have the same analyzer as one field and searches for each term in any of them.
• phrase: Runs a match_phrase query on each field. Uses the _score of the best-matching field.
• phrase_prefix: Runs a match_phrase_prefix query on each field. Uses the _score of the best-matching field.
• bool_prefix: Runs a match_bool_prefix query on each field. Uses the sum of the scores of all matching fields.

The best_fields and most_fields types are field centric: they build one query for each field and then combine the per-field scores. The cross_fields type is term centric: it looks up each query term across all fields together. Not every parameter applies to every type. For more information, see Parameter support by type.

Best fields

Use the best_fields type when the query terms are most meaningful if they appear together in the same field. For example, northern lights in a single field is a stronger match than northern in one field and lights in another.

For example, consider an index that contains the following scientific articles:

PUT /articles/_doc/1
{
  "title": "Aurora borealis",
  "description": "Northern lights, or aurora borealis, explained"
}

PUT /articles/_doc/2
{
  "title": "Sun deprivation in the Northern countries",
  "description": "Using fluorescent lights for therapy"
}

You can search for articles containing northern lights in the title or description:

GET articles/_search
{
  "query": {
    "multi_match" : {
      "query": "northern lights",
      "type": "best_fields",
      "fields": [ "title", "description" ],
      "tie_breaker": 0.3
    }
  }
}

The preceding query is executed as the following dis_max query with a match query for each field:

GET /articles/_search
{
  "query": {
    "dis_max": {
      "queries": [
        { "match": { "title": "northern lights" }},
        { "match": { "description": "northern lights" }}
      ],
      "tie_breaker": 0.3
    }
  }
}

The results contain both documents, but document 1 is scored higher because both words are in the description field:

{
  "took": 5,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 2,
      "relation": "eq"
    },
    "max_score": 0.38367155,
    "hits": [
      {
        "_index": "articles",
        "_id": "1",
        "_score": 0.38367155,
        "_source": {
          "title": "Aurora borealis",
          "description": "Northern lights, or aurora borealis, explained"
        }
      },
      {
        "_index": "articles",
        "_id": "2",
        "_score": 0.2873873,
        "_source": {
          "title": "Sun deprivation in the Northern countries",
          "description": "Using fluorescent lights for therapy"
        }
      }
    ]
  }
}

The best_fields query uses the score of the best-matching field. If you specify a tie_breaker, the score is calculated using the following algorithm:

Take the score of the best-matching field and add (tie_breaker * _score) for all other matching fields.

Most fields

Use the most_fields query for multiple fields that contain the same text that is analyzed in different ways. For example, the original field may contain text analyzed with the standard analyzer and another field may contain the same text analyzed with the english analyzer, which performs stemming. The stemmed field matches the most documents, and the unstemmed field moves the closest matches to the top of the results.

The following request creates a recipes index in which the title field has an english subfield:

PUT /recipes
{
  "mappings": {
    "properties": {
      "title": { 
        "type": "text",
        "fields": {
          "english": { 
            "type": "text",
            "analyzer": "english"
          }
        }
      }
    }
  }
}

Consider the following two documents that are indexed in the recipes index:

PUT /recipes/_doc/1
{
  "title": "Buttered toasts"
}

PUT /recipes/_doc/2
{
  "title": "Buttering a toast"
}

The standard analyzer analyzes the title Buttered toasts into [buttered, toasts] and the title Buttering a toast into [buttering, a, toast]. On the other hand, the english analyzer produces the same token list [butter, toast] for both titles because it applies stemming and removes the stopword a.

The following most_fields query searches both the title field and its english subfield:

GET /recipes/_search
{
  "query": {
    "multi_match": {
      "query": "buttered toast",
      "fields": [ 
        "title",
        "title.english"
      ],
      "type": "most_fields" 
    }
  }
}

The preceding query is executed as the following Boolean query:

GET recipes/_search
{
  "query": {
    "bool": {
      "should": [
        { "match": { "title": "buttered toast" }},
        { "match": { "title.english": "buttered toast" }}
      ]
    }
  }
}

To calculate the relevance score, OpenSearch adds together the scores of all match clauses that match the document.

Both documents match the title.english field equally because their stemmed tokens are identical. In the title field, document 1 matches the term buttered and document 2 matches the term toast. Each term appears in only one document, but the title field of document 1 contains fewer tokens, so its match scores higher. Without the title.english field, documents that use a different form of a word, such as buttering, would match only on the remaining terms:

{
  "took": 2,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 2,
      "relation": "eq"
    },
    "max_score": 0.508889,
    "hits": [
      {
        "_index": "recipes",
        "_id": "1",
        "_score": 0.508889,
        "_source": {
          "title": "Buttered toasts"
        }
      },
      {
        "_index": "recipes",
        "_id": "2",
        "_score": 0.4569852,
        "_source": {
          "title": "Buttering a toast"
        }
      }
    ]
  }
}

Document 1 scores 0.34314215 for the title field and 0.16574687 for the title.english field, and its final score is the sum of the two, 0.508889.

Operator and minimum should match

The best_fields and most_fields queries generate a match query on a field basis (one per field). Thus, the minimum_should_match and operator parameters are applied to each field, which is normally not the desired behavior.

For example, consider a customers index with the following documents:

PUT customers/_doc/1 
{
  "first_name": "John",
  "last_name": "Doe"
}

PUT customers/_doc/2 
{
  "first_name": "Jane",
  "last_name": "Doe"
}

If you’re searching for John Doe in the customers index, you might construct the following query:

GET customers/_search
{
  "query": {
    "multi_match" : {
      "query": "John Doe",
      "type": "best_fields",
      "fields": [ "first_name", "last_name" ],
      "operator": "and" 
    }
  }
}

The intent of the and operator in this query is to find a document that matches John and Doe. However, the query does not return any results. You can learn how the query is executed by running the Validate Query API:

GET customers/_validate/query?explain
{
  "query": {
    "multi_match" : {
      "query":      "John Doe",
      "type":       "best_fields",
      "fields":     [ "first_name", "last_name" ],
      "operator":   "and" 
    }
  }
}

From the response, you can see that the query is trying to match both John and Doe to either the first_name or last_name field:

{
  "_shards": {
    "total": 1,
    "successful": 1,
    "failed": 0
  },
  "valid": true,
  "explanations": [
    {
      "index": "customers",
      "valid": true,
      "explanation": "((+last_name:john +last_name:doe) | (+first_name:john +first_name:doe))"
    }
  ]
}

Because neither field contains both words, no results are returned.

A better alternative for searching across fields is to use the cross_fields query. Unlike the field-centric best_fields and most_fields queries, the cross_fields query is term centric.

Cross fields

Use the cross_fields query to search for data across multiple fields. For example, if an index contains customer data, the first name and last name of the customer reside in different fields. Yet, when you search for John Doe, you want to receive documents in which John is in the first_name field and Doe is in the last_name field.

The most_fields query does not work in this case because of the following problems:

• The operator and minimum_should_match parameters are applied on a field basis instead of on a term basis.
• Term frequencies in the first_name and last_name fields can lead to unexpected results. For example, if someone’s first name happens to be Doe, a document with this name will be presumed a better match because this first name will not appear in any other documents.

One way to avoid both problems is to copy the values of first_name and last_name into a single full_name field at index time by using the copy_to mapping parameter and then search that field. The cross_fields query solves the same problems at query time, without changes to the mapping.

The cross_fields query analyzes the query string into individual terms and then searches for each of the terms in any of the fields, as if they were one field.

The following is the cross_fields query for John Doe:

GET /customers/_search
{
  "query": {
    "multi_match" : {
      "query": "John Doe",
      "type": "cross_fields",
      "fields": [ "first_name", "last_name" ],
      "operator": "and"
    }
  }
}

The response contains the only document in which both John and Doe are present:

{
  "took": 1,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 0.3979403,
    "hits": [
      {
        "_index": "customers",
        "_id": "1",
        "_score": 0.3979403,
        "_source": {
          "first_name": "John",
          "last_name": "Doe"
        }
      }
    ]
  }
}

Use the Validate Query API to see how the preceding query is executed:

GET /customers/_validate/query?explain
{
  "query": {
    "multi_match" : {
      "query": "John Doe",
      "type": "cross_fields",
      "fields": [ "first_name", "last_name" ],
      "operator": "and"
    }
  }
}

From the response, you can see that each term must be present in at least one of the fields:

{
  "_shards": {
    "total": 1,
    "successful": 1,
    "failed": 0
  },
  "valid": true,
  "explanations": [
    {
      "index": "customers",
      "valid": true,
      "explanation": "+blended(terms:[last_name:john, first_name:john]) +blended(terms:[last_name:doe, first_name:doe])"
    }
  ]
}

Each blended clause scores a term as if all of its fields were one field. To do this, OpenSearch adjusts the document frequency of the term in each field. The field in which the term is most common keeps its document frequency, and every other field receives that frequency plus one. For example, if doe appears in the last_name field of 3 documents and in the first_name field of 1 document, the Explain API reports a document frequency of 3 for last_name:doe and 4 for first_name:doe. As a result, a rare occurrence of doe in the first_name field no longer outscores the common occurrence in the last_name field, and matches in last_name, the field most likely to contain doe, score slightly higher.

The cross_fields query is usually only useful on short string fields with a boost of 1. In other cases, the score does not produce a meaningful blend of term statistics because of the way boosts, term frequencies, and length normalization contribute to the score.

The fuzziness parameter is not supported for cross_fields queries. For more information, see Parameter support by type.

Analysis

The cross_fields query blends terms only across fields that use the same search analyzer, because only those fields produce the same terms from the query string. OpenSearch groups the fields by analyzer, builds one set of blended clauses for each group, and then combines the groups in a dis_max query. The best-scoring group determines the score, and the tie_breaker parameter controls how much the other groups contribute.

For example, the following request creates a customer_names index in which the first_name and last_name fields use the default standard analyzer and their edge subfields use an edge n-gram analyzer:

PUT customer_names
{
  "settings": {
    "analysis": {
      "analyzer": {
        "my_analyzer": {
          "tokenizer": "my_tokenizer"
        }
      },
      "tokenizer": {
        "my_tokenizer": {
          "type": "edge_ngram",
          "min_gram": 2,
          "max_gram": 10
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "first_name": { 
        "type": "text",
        "fields": {
          "edge": { 
            "type": "text",
            "analyzer": "my_analyzer"
          }
        }
      },
      "last_name": { 
        "type": "text",
        "fields": {
          "edge": { 
            "type": "text",
            "analyzer": "my_analyzer"
          }
        }
      }
    }
  }
}

Index one document into the customer_names index:

PUT /customer_names/_doc/1
{
  "first_name": "John",
  "last_name": "Doe"
}

The following cross_fields query searches for John in all four fields:

GET /customer_names/_search
{
  "query": {
    "multi_match" : {
      "query": "John",
      "type": "cross_fields",
      "fields": [
        "first_name", "first_name.edge",
        "last_name",  "last_name.edge"
      ]
    }
  }
}

To see how the query is executed, run the Validate Query API:

GET /customer_names/_validate/query?explain
{
  "query": {
    "multi_match" : {
      "query": "John",
      "type": "cross_fields",
      "fields": [
        "first_name", "first_name.edge",
        "last_name",  "last_name.edge"
      ]
    }
  }
}

The response shows two groups separated by the | (dis_max) operator. The last_name and first_name fields form one group, and the last_name.edge and first_name.edge fields form another. Within the second group, the edge n-gram analyzer splits John into the terms Jo, Joh, and John. Because the custom analyzer has no lowercase filter, these terms keep their original case:

{
  "_shards": {
    "total": 1,
    "successful": 1,
    "failed": 0
  },
  "valid": true,
  "explanations": [
    {
      "index": "customer_names",
      "valid": true,
      "explanation": "(blended(terms:[last_name:john, first_name:john]) | (blended(terms:[last_name.edge:Jo, first_name.edge:Jo]) blended(terms:[last_name.edge:Joh, first_name.edge:Joh]) blended(terms:[last_name.edge:John, first_name.edge:John])))"
    }
  ]
}

Combining field groups with operator and minimum should match

The operator and minimum_should_match parameters apply to each field group separately. When groups produce different numbers of terms, this can lead to the problem described in operator and minimum_should_match. For example, with "operator": "and", the query John Doe requires the edge group to match every n-gram of John Doe, including John D and John Do, which never occur in the index. The document can then match only through the standard group.

To control each group independently, rewrite the query as two cross_fields subqueries combined in a bool query, and apply minimum_should_match to only one of the subqueries:

GET /customer_names/_search
{
  "query": {
    "bool": {
      "should": [
        {
          "multi_match": {
            "query": "John Doe",
            "type": "cross_fields",
            "fields": [
              "first_name",
              "last_name"
            ],
            "minimum_should_match": "1"
          }
        },
        {
          "multi_match": {
            "query": "John Doe",
            "type": "cross_fields",
            "fields": [
              "first_name.edge",
              "last_name.edge"
            ]
          }
        }
      ]
    }
  }
}

Forcing all fields into one group

To place all fields in one group, specify an analyzer in the query. OpenSearch then analyzes the query string once using that analyzer and searches for the resulting terms in every field:

GET customer_names/_search
{
  "query": {
   "multi_match" : {
      "query": "John Doe",
      "type": "cross_fields",
      "analyzer": "standard", 
      "fields": [ "first_name", "last_name", "*.edge" ]
    }
  }
}

Running the Validate Query API on the preceding query shows one blended clause for each term, covering all four fields:

{
  "_shards": {
    "total": 1,
    "successful": 1,
    "failed": 0
  },
  "valid": true,
  "explanations": [
    {
      "index": "customer_names",
      "valid": true,
      "explanation": "blended(terms:[last_name.edge:john, last_name:john, first_name:john, first_name.edge:john]) blended(terms:[last_name.edge:doe, last_name:doe, first_name:doe, first_name.edge:doe])"
    }
  ]
}

When you override the analyzer, the query terms no longer match the way the subfields were indexed. In this example, the standard analyzer produces the lowercase term jo for the query Jo, but the edge subfields contain only Jo. As a result, a search for Jo using "analyzer": "standard" returns no documents, while the same search without the analyzer parameter matches document 1 through the edge subfields. Override the analyzer only when all grouped fields can match the terms it produces.

Phrase

The phrase query behaves similarly to the best_fields query but uses a match_phrase query instead of a match query.

The following is an example phrase query for the index described in the best_fields section:

GET articles/_search
{
  "query": {
    "multi_match" : {
      "query": "northern lights",
      "type": "phrase",
      "fields": [ "title", "description" ]
    }
  }
}

The preceding query is executed as the following dis_max query with a match_phrase query for each field:

GET articles/_search
{
  "query": {
    "dis_max": {
      "queries": [
        { "match_phrase": { "title": "northern lights" }},
        { "match_phrase": { "description": "northern lights" }}
      ]
    }
  }
}

By default, a phrase query matches only when the terms appear next to each other in the same order. Document 2 contains both terms but not as a phrase, so only document 1 is returned in the results:

{
  "took": 1,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 0.38367155,
    "hits": [
      {
        "_index": "articles",
        "_id": "1",
        "_score": 0.38367155,
        "_source": {
          "title": "Aurora borealis",
          "description": "Northern lights, or aurora borealis, explained"
        }
      }
    ]
  }
}

Use the slop parameter to allow other words between the words in the query phrase. For example, the following query accepts text as a match if up to two words are between fluorescent and therapy:

GET articles/_search
{
  "query": {
    "multi_match" : {
      "query": "fluorescent therapy",
      "type": "phrase",
      "fields": [ "title", "description" ],
      "slop": 2
    }
  }
}

The response contains document 2:

{
  "took": 1,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 0.31835568,
    "hits": [
      {
        "_index": "articles",
        "_id": "2",
        "_score": 0.31835568,
        "_source": {
          "title": "Sun deprivation in the Northern countries",
          "description": "Using fluorescent lights for therapy"
        }
      }
    ]
  }
}

For slop values less than 2, no documents are returned.

The fuzziness parameter is not supported for phrase queries. For more information, see Parameter support by type.

Phrase prefix

The phrase_prefix query behaves similarly to the phrase query but uses a match_phrase_prefix query instead of a match_phrase query.

The following is an example phrase_prefix query for the index described in the best_fields section:

GET articles/_search
{
  "query": {
    "multi_match" : {
      "query": "northern light",
      "type": "phrase_prefix",
      "fields": [ "title", "description" ]
    }
  }
}

The preceding query is executed as the following dis_max query with a match_phrase_prefix query for each field:

GET articles/_search
{
  "query": {
    "dis_max": {
      "queries": [
        { "match_phrase_prefix": { "title": "northern light" }},
        { "match_phrase_prefix": { "description": "northern light" }}
      ]
    }
  }
}

The phrase_prefix type accepts the slop parameter, which works the same way as for the phrase type. It also accepts the max_expansions parameter, which limits the number of terms to which the last term in the query is expanded. Default is 50.

The fuzziness parameter is not supported for phrase_prefix queries. For more information, see Parameter support by type.

Boolean prefix

The bool_prefix query scores documents similarly to the most_fields query but uses a match_bool_prefix query instead of a match query. The match_bool_prefix query matches every term except the last one exactly and treats the last term as a prefix, which makes it useful for search-as-you-type experiences.

The following is an example bool_prefix query for the index described in the best_fields section:

GET articles/_search
{
  "query": {
    "multi_match" : {
      "query": "northern li",
      "type": "bool_prefix",
      "fields": [ "title", "description" ]
    }
  }
}

The preceding query is executed as the following Boolean query with a match_bool_prefix query for each field. The scores of all matching clauses are added together:

GET articles/_search
{
  "query": {
    "bool": {
      "should": [
        { "match_bool_prefix": { "title": "northern li" }},
        { "match_bool_prefix": { "description": "northern li" }}
      ]
    }
  }
}

Both documents are returned. Document 1 matches northern and the prefix li (lights) in the description field. Document 2 matches northern in the title field and the prefix li in the description field:

{
  "took": 2,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 2,
      "relation": "eq"
    },
    "max_score": 1.3037697,
    "hits": [
      {
        "_index": "articles",
        "_id": "1",
        "_score": 1.3037697,
        "_source": {
          "title": "Aurora borealis",
          "description": "Northern lights, or aurora borealis, explained"
        }
      },
      {
        "_index": "articles",
        "_id": "2",
        "_score": 1.261565,
        "_source": {
          "title": "Sun deprivation in the Northern countries",
          "description": "Using fluorescent lights for therapy"
        }
      }
    ]
  }
}

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 they do not have an effect on the prefix query constructed from the final term. The slop parameter is not supported for bool_prefix queries.

Parameters

The query accepts the following parameters. All parameters except query are optional.

Parameter support by type

Not every parameter applies to every query type. OpenSearch rejects the following combinations with a 400 error.

Other parameters that a query type does not use are ignored without an error. For example, the slop parameter has no effect on best_fields or most_fields queries. The following table lists the parameters that have an effect for each query type, in addition to query, fields, type, analyzer, boost, lenient, and zero_terms_query, which apply to all types.

For the bool_prefix type, the fuzzy parameters apply to every term except the last one, which is always matched as a prefix.

The tie_breaker parameter

The tie_breaker parameter determines how the scores of matching fields are combined. For the cross_fields type, it also determines how the scores of the fields within each blended clause and of the field groups are combined. The tie_breaker parameter accepts the following values:

• 0.0 (default for best_fields, cross_fields, phrase, and phrase_prefix queries): Take the single best score returned by any field in a group.
• 1.0 (default for most_fields and bool_prefix queries): Add the scores for all fields in a group.
• A floating-point value in the (0, 1) range: Take the single best score of the best-matching field and add (tie_breaker * _score) for all other matching fields.