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

[[query-dsl-term-query]]
=== Term query
++++
<titleabbrev>Term</titleabbrev>
++++

Returns documents that contain an *exact* term in a provided field.

You can use the `term` query to find documents based on a precise value such as
a price, a product ID, or a username.

[WARNING]
====
Avoid using the `term` query for <<text, `text`>> fields.

By default, {es} changes the values of `text` fields as part of <<analysis,
analysis>>. This can make finding exact matches for `text` field values
difficult.

To search `text` field values, use the <<query-dsl-match-query,`match`>> query
instead.
====

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

[source,console]
----
GET /_search
{
  "query": {
    "term": {
      "user": {
        "value": "Kimchy",
        "boost": 1.0
      }
    }
  }
}
----

[[term-top-level-params]]
==== Top-level parameters for `term`
`<field>`::
(Required, object) Field you wish to search.

[[term-field-params]]
==== Parameters for `<field>`
`value`::
(Required, string) Term you wish to find in the provided `<field>`. To return a
document, the term must exactly match the field value, including whitespace and
capitalization.

`boost`::
(Optional, float) Floating point number used to decrease or increase the
<<relevance-scores,relevance scores>> of a query. Defaults to `1.0`.
+
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.

[[term-query-notes]]
==== Notes

[[avoid-term-query-text-fields]]
===== Avoid using the `term` query for `text` fields
By default, {es} changes the values of `text` fields during analysis. For
example, the default <<analysis-standard-analyzer, standard analyzer>> changes
`text` field values as follows:

* Removes most punctuation
* Divides the remaining content into individual words, called
<<analysis-tokenizers, tokens>>
* Lowercases the tokens

To better search `text` fields, the `match` query also analyzes your provided
search term before performing a search. This means the `match` query can search
`text` fields for analyzed tokens rather than an exact term.

The `term` query does *not* analyze the search term. The `term` query only
searches for the *exact* term you provide. This means the `term` query may
return poor or no results when searching `text` fields.

To see the difference in search results, try the following example.  

. Create an index with a `text` field called `full_text`.
+
--

[source,console]
----
PUT my_index
{
  "mappings": {
    "properties": {
      "full_text": { "type": "text" }
    }
  }
}
----

--

. Index a document with a value of `Quick Brown Foxes!` in the `full_text`
field.
+
--

[source,console]
----
PUT my_index/_doc/1
{
  "full_text":   "Quick Brown Foxes!"
}
----
// TEST[continued]

Because `full_text` is a `text` field, {es} changes `Quick Brown Foxes!` to
`[quick, brown, fox]` during analysis.

--

. Use the `term` query to search for `Quick Brown Foxes!` in the `full_text`
field. Include the `pretty` parameter so the response is more readable.
+
--

[source,console]
----
GET my_index/_search?pretty
{
  "query": {
    "term": {
      "full_text": "Quick Brown Foxes!"
    }
  }
}
----
// TEST[continued]

Because the `full_text` field no longer contains the *exact* term `Quick Brown
Foxes!`, the `term` query search returns no results.

--

. Use the `match` query to search for `Quick Brown Foxes!` in the `full_text`
field.
+
--

////

[source,console]
----
POST my_index/_refresh
----
// TEST[continued]

////

[source,console]
----
GET my_index/_search?pretty
{
  "query": {
    "match": {
      "full_text": "Quick Brown Foxes!"
    }
  }
}
----
// TEST[continued]

Unlike the `term` query, the `match` query analyzes your provided search term,
`Quick Brown Foxes!`, before performing a search. The `match` query then returns
any documents containing the `quick`, `brown`, or `fox` tokens in the
`full_text` field.

Here's the response for the `match` query search containing the indexed document
in the results.

[source,console-result]
----
{
  "took" : 1,
  "timed_out" : false,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 1,
      "relation" : "eq"
    },
    "max_score" : 0.8630463,
    "hits" : [
      {
        "_index" : "my_index",
        "_type" : "_doc",
        "_id" : "1",
        "_score" : 0.8630463,
        "_source" : {
          "full_text" : "Quick Brown Foxes!"
        }
      }
    ]
  }
}
----
// TESTRESPONSE[s/"took" : 1/"took" : $body.took/]
--