Theterms_set query is the same as theterms query, except you can define the number of matching terms required to return a document. For example:

• A field,programming_languages, contains a list of known programming languages, such asc++,java, orphp for job candidates. You can use theterms_set query to return documents that match at least two of these languages.
• A field,permissions, contains a list of possible user permissions for an application. You can use theterms_set query to return documents that match a subset of these permissions.

In most cases, you’ll need to include anumeric field mapping in your index to use theterms_set query. This numeric field contains the number of matching terms required to return a document.

To see how you can set up an index for theterms_set query, try the following example.

1. Create an index,job-candidates, with the following field mappings:

   • name, akeyword field. This field contains the name of the job candidate.
   • programming_languages, akeyword field. This field contains programming languages known by the job candidate.
   • required_matches, anumericlong field. This field contains the number of matching terms required to return a document.

   PUT /job-candidates{  "mappings": {    "properties": {      "name": {        "type": "keyword"      },      "programming_languages": {        "type": "keyword"      },      "required_matches": {        "type": "long"      }    }  }}

2. Index a document with an ID of1 and the following values:

   • Jane Smith in thename field.
   • ["c++", "java"] in theprogramming_languages field.
   • 2 in therequired_matches field.

   Include the?refresh parameter so the document is immediately available for search.

   PUT /job-candidates/_doc/1?refresh{  "name": "Jane Smith",  "programming_languages": [ "c++", "java" ],  "required_matches": 2}

3. Index another document with an ID of2 and the following values:

   • Jason Response in thename field.
   • ["java", "php"] in theprogramming_languages field.
   • 2 in therequired_matches field.

   PUT /job-candidates/_doc/2?refresh{  "name": "Jason Response",  "programming_languages": [ "java", "php" ],  "required_matches": 2}

You can now use therequired_matches field value as the number of matching terms required to return a document in theterms_set query.

The following search returns documents where theprogramming_languages field contains at least two of the following terms:

• c++
• java
• php

Theminimum_should_match_field isrequired_matches. This means the number of matching terms required is2, the value of therequired_matches field.

GET /job-candidates/_search{  "query": {    "terms_set": {      "programming_languages": {        "terms": [ "c++", "java", "php" ],        "minimum_should_match_field": "required_matches"      }    }  }}

<field>

(Required, object) Field you wish to search.

terms

(Required, array) Array of terms you wish to find in the provided<field>. To return a document, a required number of terms must exactly match the field values, including whitespace and capitalization.

The required number of matching terms is defined in theminimum_should_match,minimum_should_match_field orminimum_should_match_script parameters. Exactly one of these parameters must be provided.

minimum_should_match

(Optional) Specification for the number of matching terms required to return a document.

For valid values, seeminimum_should_match parameter.

minimum_should_match_field

(Optional, string)Numeric field containing the number of matching terms required to return a document.

minimum_should_match_script

(Optional, string) Custom script containing the number of matching terms required to return a document.

For parameters and valid values, seeScripting.

For an example query using theminimum_should_match_script parameter, seeHow to use theminimum_should_match_script parameter.

You can useminimum_should_match_script to define the required number of matching terms using a script. This is useful if you need to set the number of required terms dynamically.

The following search returns documents where theprogramming_languages field contains at least two of the following terms:

• c++
• java
• php

Thesource parameter of this query indicates:

• The required number of terms to match cannot exceedparams.num_terms, the number of terms provided in theterms field.
• The required number of terms to match is2, the value of therequired_matches field.

GET /job-candidates/_search{  "query": {    "terms_set": {      "programming_languages": {        "terms": [ "c++", "java", "php" ],        "minimum_should_match_script": {          "source": "Math.min(params.num_terms, doc['required_matches'].value)"        },        "boost": 1.0      }    }  }}