match-query.asciidoc 7.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234
  1. [[query-dsl-match-query]]
  2. === Match Query
  3. A family of `match` queries that accept text/numerics/dates, analyzes
  4. it, and constructs a query out of it. For example:
  5. [source,js]
  6. --------------------------------------------------
  7. {
  8. "match" : {
  9. "message" : "this is a test"
  10. }
  11. }
  12. --------------------------------------------------
  13. Note, `message` is the name of a field, you can substitute the name of
  14. any field (including `_all`) instead.
  15. [float]
  16. ==== Types of Match Queries
  17. [float]
  18. ===== boolean
  19. The default `match` query is of type `boolean`. It means that the text
  20. provided is analyzed and the analysis process constructs a boolean query
  21. from the provided text. The `operator` flag can be set to `or` or `and`
  22. to control the boolean clauses (defaults to `or`). The minimum number of
  23. should clauses to match can be set using the
  24. <<query-dsl-minimum-should-match,`minimum_should_match`>>
  25. parameter.
  26. The `analyzer` can be set to control which analyzer will perform the
  27. analysis process on the text. It default to the field explicit mapping
  28. definition, or the default search analyzer.
  29. `fuzziness` allows _fuzzy matching_ based on the type of field being queried.
  30. See <<fuzziness>> for allowed settings.
  31. The `prefix_length` and
  32. `max_expansions` can be set in this case to control the fuzzy process.
  33. If the fuzzy option is set the query will use `constant_score_rewrite`
  34. as its <<query-dsl-multi-term-rewrite,rewrite
  35. method>> the `rewrite` parameter allows to control how the query will get
  36. rewritten.
  37. Here is an example when providing additional parameters (note the slight
  38. change in structure, `message` is the field name):
  39. [source,js]
  40. --------------------------------------------------
  41. {
  42. "match" : {
  43. "message" : {
  44. "query" : "this is a test",
  45. "operator" : "and"
  46. }
  47. }
  48. }
  49. --------------------------------------------------
  50. .zero_terms_query
  51. If the analyzer used removes all tokens in a query like a `stop` filter
  52. does, the default behavior is to match no documents at all. In order to
  53. change that the `zero_terms_query` option can be used, which accepts
  54. `none` (default) and `all` which corresponds to a `match_all` query.
  55. [source,js]
  56. --------------------------------------------------
  57. {
  58. "match" : {
  59. "message" : {
  60. "query" : "to be or not to be",
  61. "operator" : "and",
  62. "zero_terms_query": "all"
  63. }
  64. }
  65. }
  66. --------------------------------------------------
  67. .cutoff_frequency
  68. The match query supports a `cutoff_frequency` that allows
  69. specifying an absolute or relative document frequency where high
  70. frequent terms are moved into an optional subquery and are only scored
  71. if one of the low frequent (below the cutoff) terms in the case of an
  72. `or` operator or all of the low frequent terms in the case of an `and`
  73. operator match.
  74. This query allows handling `stopwords` dynamically at runtime, is domain
  75. independent and doesn't require on a stopword file. It prevent scoring /
  76. iterating high frequent terms and only takes the terms into account if a
  77. more significant / lower frequent terms match a document. Yet, if all of
  78. the query terms are above the given `cutoff_frequency` the query is
  79. automatically transformed into a pure conjunction (`and`) query to
  80. ensure fast execution.
  81. The `cutoff_frequency` can either be relative to the number of documents
  82. in the index if in the range `[0..1)` or absolute if greater or equal to
  83. `1.0`.
  84. Note: If the `cutoff_frequency` is used and the operator is `and`
  85. _stacked tokens_ (tokens that are on the same position like `synonym` filter emits)
  86. are not handled gracefully as they are in a pure `and` query. For instance the query
  87. `fast fox` is analyzed into 3 terms `[fast, quick, fox]` where `quick` is a synonym
  88. for `fast` on the same token positions the query might require `fast` and `quick` to
  89. match if the operator is `and`.
  90. Here is an example showing a query composed of stopwords exclusivly:
  91. [source,js]
  92. --------------------------------------------------
  93. {
  94. "match" : {
  95. "message" : {
  96. "query" : "to be or not to be",
  97. "cutoff_frequency" : 0.001
  98. }
  99. }
  100. }
  101. --------------------------------------------------
  102. [float]
  103. ===== phrase
  104. The `match_phrase` query analyzes the text and creates a `phrase` query
  105. out of the analyzed text. For example:
  106. [source,js]
  107. --------------------------------------------------
  108. {
  109. "match_phrase" : {
  110. "message" : "this is a test"
  111. }
  112. }
  113. --------------------------------------------------
  114. Since `match_phrase` is only a `type` of a `match` query, it can also be
  115. used in the following manner:
  116. [source,js]
  117. --------------------------------------------------
  118. {
  119. "match" : {
  120. "message" : {
  121. "query" : "this is a test",
  122. "type" : "phrase"
  123. }
  124. }
  125. }
  126. --------------------------------------------------
  127. A phrase query matches terms up to a configurable `slop`
  128. (which defaults to 0) in any order. Transposed terms have a slop of 2.
  129. The `analyzer` can be set to control which analyzer will perform the
  130. analysis process on the text. It default to the field explicit mapping
  131. definition, or the default search analyzer, for example:
  132. [source,js]
  133. --------------------------------------------------
  134. {
  135. "match_phrase" : {
  136. "message" : {
  137. "query" : "this is a test",
  138. "analyzer" : "my_analyzer"
  139. }
  140. }
  141. }
  142. --------------------------------------------------
  143. [float]
  144. ===== match_phrase_prefix
  145. The `match_phrase_prefix` is the same as `match_phrase`, except that it
  146. allows for prefix matches on the last term in the text. For example:
  147. [source,js]
  148. --------------------------------------------------
  149. {
  150. "match_phrase_prefix" : {
  151. "message" : "this is a test"
  152. }
  153. }
  154. --------------------------------------------------
  155. Or:
  156. [source,js]
  157. --------------------------------------------------
  158. {
  159. "match" : {
  160. "message" : {
  161. "query" : "this is a test",
  162. "type" : "phrase_prefix"
  163. }
  164. }
  165. }
  166. --------------------------------------------------
  167. It accepts the same parameters as the phrase type. In addition, it also
  168. accepts a `max_expansions` parameter that can control to how many
  169. prefixes the last term will be expanded. It is highly recommended to set
  170. it to an acceptable value to control the execution time of the query.
  171. For example:
  172. [source,js]
  173. --------------------------------------------------
  174. {
  175. "match_phrase_prefix" : {
  176. "message" : {
  177. "query" : "this is a test",
  178. "max_expansions" : 10
  179. }
  180. }
  181. }
  182. --------------------------------------------------
  183. [float]
  184. ==== Comparison to query_string / field
  185. The match family of queries does not go through a "query parsing"
  186. process. It does not support field name prefixes, wildcard characters,
  187. or other "advance" features. For this reason, chances of it failing are
  188. very small / non existent, and it provides an excellent behavior when it
  189. comes to just analyze and run that text as a query behavior (which is
  190. usually what a text search box does). Also, the `phrase_prefix` type can
  191. provide a great "as you type" behavior to automatically load search
  192. results.
  193. [float]
  194. ==== Other options
  195. * `lenient` - If set to true will cause format based failures (like
  196. providing text to a numeric field) to be ignored. Defaults to false.