OpenSearch/docs/reference/query-dsl/terms-set-query.asciidoc

[[query-dsl-terms-set-query]]
=== Terms Set Query

experimental[The terms_set query is a new query and its syntax may change in the future]

Returns any documents that match with at least one or more of the
provided terms. The terms are not analyzed and thus must match exactly.
The number of terms that must match varies per document and is either
controlled by a minimum should match field or computed per document in
a minimum should match script.

The field that controls the number of required terms that must match must
be a number field:

[source,js]
--------------------------------------------------
PUT /my-index
{
    "mappings": {
        "_doc": {
            "properties": {
                "required_matches": {
                    "type": "long"
                }
            }
        }
    }
}

PUT /my-index/_doc/1?refresh
{
    "codes": ["ghi", "jkl"],
    "required_matches": 2
}

PUT /my-index/_doc/2?refresh
{
    "codes": ["def", "ghi"],
    "required_matches": 2
}
--------------------------------------------------
// CONSOLE
// TESTSETUP

An example that uses the minimum should match field:

[source,js]
--------------------------------------------------
GET /my-index/_search
{
    "query": {
        "terms_set": {
            "codes" : {
                "terms" : ["abc", "def", "ghi"],
                "minimum_should_match_field": "required_matches"
            }
        }
    }
}
--------------------------------------------------
// CONSOLE

Response:

[source,js]
--------------------------------------------------
{
  "took": 13,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped" : 0,
    "failed": 0
  },
  "hits": {
    "total": 1,
    "max_score": 0.87546873,
    "hits": [
      {
        "_index": "my-index",
        "_type": "_doc",
        "_id": "2",
        "_score": 0.87546873,
        "_source": {
          "codes": ["def", "ghi"],
          "required_matches": 2
        }
      }
    ]
  }
}
--------------------------------------------------
// TESTRESPONSE[s/"took": 13,/"took": "$body.took",/]

Scripts can also be used to control how many terms are required to match
in a more dynamic way. For example a create date or a popularity field
can be used as basis for the number of required terms to match.

Also the `params.num_terms` parameter is available in the script to indicate the
number of terms that have been specified.

An example that always limits the number of required terms to match to never
become larger than the number of terms specified:

[source,js]
--------------------------------------------------
GET /my-index/_search
{
    "query": {
        "terms_set": {
            "codes" : {
                "terms" : ["abc", "def", "ghi"],
                "minimum_should_match_script": {
                   "source": "Math.min(params.num_terms, doc['required_matches'].value)"
                }
            }
        }
    }
}
--------------------------------------------------
// CONSOLE