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

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

Returns documents that contain one or more *exact* terms in a provided field.

The `terms` query is the same as the <<query-dsl-term-query, `term` query>>,
except you can search for multiple values.

[[terms-query-ex-request]]
==== Example request

The following search returns documents where the `user` field contains `kimchy`
or `elasticsearch`.

[source,js]
----
GET /_search
{
    "query" : {
        "terms" : {
            "user" : ["kimchy", "elasticsearch"],
            "boost" : 1.0 
        }
    }
}
----
// CONSOLE

[[terms-top-level-params]]
==== Top-level parameters for `terms`
`<field>`::
+
--
Field you wish to search.

The value of this parameter is an array of terms you wish to find in the
provided field. To return a document, one or more terms must exactly match a
field value, including whitespace and capitalization.

By default, {es} limits the `terms` query to a maximum of 65,536
terms. You can change this limit using the <<index-max-terms-count,
`index.max_terms_count`>> setting.

[NOTE]
To use the field values of an existing document as search terms, use the
<<query-dsl-terms-lookup, terms lookup>> parameters.
--

`boost`::
+
--
Floating point number used to decrease or increase the
<<query-filter-context, relevance scores>> of a query. Default is `1.0`.
Optional.

You can use the `boost` parameter to adjust relevance scores for searches
containing two or more queries.

Boost values are relative to the default value of `1.0`. A boost value between
`0` and `1.0` decreases the relevance score. A value greater than `1.0`
increases the relevance score.
--

[[terms-query-notes]]
==== Notes

[[query-dsl-terms-query-highlighting]]
===== Highlighting `terms` queries
<<search-request-highlighting,Highlighting>> is best-effort only. {es} may not
return highlight results for `terms` queries depending on:

* Highlighter type
* Number of terms in the query

[[query-dsl-terms-lookup]]
===== Terms lookup
Terms lookup fetches the field values of an existing document. {es} then uses
those values as search terms. This can be helpful when searching for a large set
of terms.

Because terms lookup fetches values from a document, the <<mapping-source-field,
`_source`>> mapping field must be enabled to use terms lookup. The `_source`
field is enabled by default.

[NOTE]
By default, {es} limits the `terms` query to a maximum of 65,536
terms. This includes terms fetched using terms lookup. You can change
this limit using the <<index-max-terms-count, `index.max_terms_count`>> setting.

To perform a terms lookup, use the following parameters.

[[query-dsl-terms-lookup-params]]
====== Terms lookup parameters
`index`::
Name of the index from which to fetch field values.

`id`::
<<mapping-id-field,ID>> of the document from which to fetch field values.

`path`::
+
--
Name of the field from which to fetch field values. {es} uses
these values as search terms for the query.

If the field values include an array of nested inner objects, you can access
those objects using dot notation syntax.
--

`routing`::
Custom <<mapping-routing-field, routing value>> of the document from which to
fetch term values. If a custom routing value was provided when the document was
indexed, this parameter is required.

[[query-dsl-terms-lookup-example]]
====== Terms lookup example

To see how terms lookup works, try the following example.  

. Create an index with a `keyword` field named `color`.
+
--

[source,js]
----
PUT my_index
{
    "mappings" : {
        "properties" : {
            "color" : { "type" : "keyword" }
        }
    }
}
----
// CONSOLE
--

. Index a document with an ID of 1 and values of `["blue", "green"]` in the
`color` field.
+
--

[source,js]
----
PUT my_index/_doc/1
{
  "color":   ["blue", "green"]
}
----
// CONSOLE
// TEST[continued]
--

. Index another document with an ID of 2 and value of `blue` in the `color`
field.
+
--

[source,js]
----
PUT my_index/_doc/2
{
  "color":   "blue"
}
----
// CONSOLE
// TEST[continued]
--

. Use the `terms` query with terms lookup parameters to find documents
containing one or more of the same terms as document 2. Include the `pretty`
parameter so the response is more readable.
+
--

////

[source,js]
----
POST my_index/_refresh
----
// CONSOLE
// TEST[continued]

////

[source,js]
----
GET my_index/_search?pretty
{
  "query": {
    "terms": {
        "color" : {
            "index" : "my_index",
            "id" : "2",
            "path" : "color"
        }
    }
  }
}
----
// CONSOLE
// TEST[continued]

Because document 2 and document 1 both contain `blue` as a value in the `color`
field, {es} returns both documents.

[source,js]
----
{
  "took" : 17,
  "timed_out" : false,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 2,
      "relation" : "eq"
    },
    "max_score" : 1.0,
    "hits" : [
      {
        "_index" : "my_index",
        "_type" : "_doc",
        "_id" : "1",
        "_score" : 1.0,
        "_source" : {
          "color" : [
            "blue",
            "green"
          ]
        }
      },
      {
        "_index" : "my_index",
        "_type" : "_doc",
        "_id" : "2",
        "_score" : 1.0,
        "_source" : {
          "color" : "blue"
        }
      }
    ]
  }
}
----
// TESTRESPONSE[s/"took" : 17/"took" : $body.took/]
--