elasticsearch/docs/reference/query-languages/query-dsl/query-dsl-terms-set-query.md

---
navigation_title: "Terms set"
mapped_pages:
  - https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-terms-set-query.html
---

# Terms set query [query-dsl-terms-set-query]


Returns documents that contain a minimum number of **exact** terms in a provided field.

The `terms_set` query is the same as the [`terms` query](/reference/query-languages/query-dsl/query-dsl-terms-query.md), 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 as `c++`, `java`, or `php` for job candidates. You can use the `terms_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 the `terms_set` query to return documents that match a subset of these permissions.

## Example request [terms-set-query-ex-request]

### Index setup [terms-set-query-ex-request-index-setup]

In most cases, you’ll need to include a [numeric](/reference/elasticsearch/mapping-reference/number.md) field mapping in your index to use the `terms_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 the `terms_set` query, try the following example.

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

    * `name`, a [`keyword`](/reference/elasticsearch/mapping-reference/keyword.md) field. This field contains the name of the job candidate.
    * `programming_languages`, a [`keyword`](/reference/elasticsearch/mapping-reference/keyword.md) field. This field contains programming languages known by the job candidate.
    * `required_matches`, a [numeric](/reference/elasticsearch/mapping-reference/number.md) `long` field. This field contains the number of matching terms required to return a document.

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

2. Index a document with an ID of `1` and the following values:

    * `Jane Smith` in the `name` field.
    * `["c++", "java"]` in the `programming_languages` field.
    * `2` in the `required_matches` field.

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

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

3. Index another document with an ID of `2` and the following values:

    * `Jason Response` in the `name` field.
    * `["java", "php"]` in the `programming_languages` field.
    * `2` in the `required_matches` field.

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


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


### Example query [terms-set-query-ex-request-query]

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

* `c++`
* `java`
* `php`

The `minimum_should_match_field` is `required_matches`. This means the number of matching terms required is `2`, the value of the `required_matches` field.

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



## Top-level parameters for `terms_set` [terms-set-top-level-params]

`<field>`
:   (Required, object) Field you wish to search.


## Parameters for `<field>` [terms-set-field-params]

`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 the `minimum_should_match`, `minimum_should_match_field` or `minimum_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, see [`minimum_should_match` parameter](/reference/query-languages/query-dsl/query-dsl-minimum-should-match.md).


`minimum_should_match_field`
:   (Optional, string) [Numeric](/reference/elasticsearch/mapping-reference/number.md) 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, see [Scripting](docs-content://explore-analyze/scripting.md).

For an example query using the `minimum_should_match_script` parameter, see [How to use the `minimum_should_match_script` parameter](#terms-set-query-script).



## Notes [terms-set-query-notes]

### How to use the `minimum_should_match_script` parameter [terms-set-query-script]

You can use `minimum_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.

#### Example query using `minimum_should_match_script` [terms-set-query-script-ex]

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

* `c++`
* `java`
* `php`

The `source` parameter of this query indicates:

* The required number of terms to match cannot exceed `params.num_terms`, the number of terms provided in the `terms` field.
* The required number of terms to match is `2`, the value of the `required_matches` field.

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