term-query.asciidoc 4.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221
  1. [[query-dsl-term-query]]
  2. === Term query
  3. ++++
  4. <titleabbrev>Term</titleabbrev>
  5. ++++
  6. Returns documents that contain an *exact* term in a provided field.
  7. You can use the `term` query to find documents based on a precise value such as
  8. a price, a product ID, or a username.
  9. [WARNING]
  10. ====
  11. Avoid using the `term` query for <<text, `text`>> fields.
  12. By default, {es} changes the values of `text` fields as part of <<analysis,
  13. analysis>>. This can make finding exact matches for `text` field values
  14. difficult.
  15. To search `text` field values, use the <<query-dsl-match-query,`match`>> query
  16. instead.
  17. ====
  18. [[term-query-ex-request]]
  19. ==== Example request
  20. [source,console]
  21. ----
  22. GET /_search
  23. {
  24. "query": {
  25. "term": {
  26. "user.id": {
  27. "value": "kimchy",
  28. "boost": 1.0
  29. }
  30. }
  31. }
  32. }
  33. ----
  34. [[term-top-level-params]]
  35. ==== Top-level parameters for `term`
  36. `<field>`::
  37. (Required, object) Field you wish to search.
  38. [[term-field-params]]
  39. ==== Parameters for `<field>`
  40. `value`::
  41. (Required, string) Term you wish to find in the provided `<field>`. To return a
  42. document, the term must exactly match the field value, including whitespace and
  43. capitalization.
  44. `boost`::
  45. (Optional, float) Floating point number used to decrease or increase the
  46. <<relevance-scores,relevance scores>> of a query. Defaults to `1.0`.
  47. +
  48. You can use the `boost` parameter to adjust relevance scores for searches
  49. containing two or more queries.
  50. +
  51. Boost values are relative to the default value of `1.0`. A boost value between
  52. `0` and `1.0` decreases the relevance score. A value greater than `1.0`
  53. increases the relevance score.
  54. `case_insensitive` added:[7.10.0]::
  55. (Optional, Boolean) Allows ASCII case insensitive matching of the
  56. value with the indexed field values when set to true. Default is false which means
  57. the case sensitivity of matching depends on the underlying field's mapping.
  58. [[term-query-notes]]
  59. ==== Notes
  60. [[avoid-term-query-text-fields]]
  61. ===== Avoid using the `term` query for `text` fields
  62. By default, {es} changes the values of `text` fields during analysis. For
  63. example, the default <<analysis-standard-analyzer, standard analyzer>> changes
  64. `text` field values as follows:
  65. * Removes most punctuation
  66. * Divides the remaining content into individual words, called
  67. <<analysis-tokenizers, tokens>>
  68. * Lowercases the tokens
  69. To better search `text` fields, the `match` query also analyzes your provided
  70. search term before performing a search. This means the `match` query can search
  71. `text` fields for analyzed tokens rather than an exact term.
  72. The `term` query does *not* analyze the search term. The `term` query only
  73. searches for the *exact* term you provide. This means the `term` query may
  74. return poor or no results when searching `text` fields.
  75. To see the difference in search results, try the following example.
  76. . Create an index with a `text` field called `full_text`.
  77. +
  78. --
  79. [source,console]
  80. ----
  81. PUT my-index-000001
  82. {
  83. "mappings": {
  84. "properties": {
  85. "full_text": { "type": "text" }
  86. }
  87. }
  88. }
  89. ----
  90. --
  91. . Index a document with a value of `Quick Brown Foxes!` in the `full_text`
  92. field.
  93. +
  94. --
  95. [source,console]
  96. ----
  97. PUT my-index-000001/_doc/1
  98. {
  99. "full_text": "Quick Brown Foxes!"
  100. }
  101. ----
  102. // TEST[continued]
  103. Because `full_text` is a `text` field, {es} changes `Quick Brown Foxes!` to
  104. `[quick, brown, fox]` during analysis.
  105. --
  106. . Use the `term` query to search for `Quick Brown Foxes!` in the `full_text`
  107. field. Include the `pretty` parameter so the response is more readable.
  108. +
  109. --
  110. [source,console]
  111. ----
  112. GET my-index-000001/_search?pretty
  113. {
  114. "query": {
  115. "term": {
  116. "full_text": "Quick Brown Foxes!"
  117. }
  118. }
  119. }
  120. ----
  121. // TEST[continued]
  122. Because the `full_text` field no longer contains the *exact* term `Quick Brown
  123. Foxes!`, the `term` query search returns no results.
  124. --
  125. . Use the `match` query to search for `Quick Brown Foxes!` in the `full_text`
  126. field.
  127. +
  128. --
  129. ////
  130. [source,console]
  131. ----
  132. POST my-index-000001/_refresh
  133. ----
  134. // TEST[continued]
  135. ////
  136. [source,console]
  137. ----
  138. GET my-index-000001/_search?pretty
  139. {
  140. "query": {
  141. "match": {
  142. "full_text": "Quick Brown Foxes!"
  143. }
  144. }
  145. }
  146. ----
  147. // TEST[continued]
  148. Unlike the `term` query, the `match` query analyzes your provided search term,
  149. `Quick Brown Foxes!`, before performing a search. The `match` query then returns
  150. any documents containing the `quick`, `brown`, or `fox` tokens in the
  151. `full_text` field.
  152. Here's the response for the `match` query search containing the indexed document
  153. in the results.
  154. [source,console-result]
  155. ----
  156. {
  157. "took" : 1,
  158. "timed_out" : false,
  159. "_shards" : {
  160. "total" : 1,
  161. "successful" : 1,
  162. "skipped" : 0,
  163. "failed" : 0
  164. },
  165. "hits" : {
  166. "total" : {
  167. "value" : 1,
  168. "relation" : "eq"
  169. },
  170. "max_score" : 0.8630463,
  171. "hits" : [
  172. {
  173. "_index" : "my-index-000001",
  174. "_id" : "1",
  175. "_score" : 0.8630463,
  176. "_source" : {
  177. "full_text" : "Quick Brown Foxes!"
  178. }
  179. }
  180. ]
  181. }
  182. }
  183. ----
  184. // TESTRESPONSE[s/"took" : 1/"took" : $body.took/]
  185. --