From 5738ba32e73b1c2a078b30b814cdda2f3978b160 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Wed, 24 Apr 2019 09:48:34 -0400 Subject: [PATCH 1/5] [DOCS] Restructure `term` query docs. * Simplifies description of `term` query * Replaces aside with warning to not use for `text` field types * Removes detailed information about boost * Adds parameters sections --- docs/reference/query-dsl/term-query.asciidoc | 197 +++++-------------- 1 file changed, 44 insertions(+), 153 deletions(-) diff --git a/docs/reference/query-dsl/term-query.asciidoc b/docs/reference/query-dsl/term-query.asciidoc index 910123bbe6177..cdb7ac79308f4 100644 --- a/docs/reference/query-dsl/term-query.asciidoc +++ b/docs/reference/query-dsl/term-query.asciidoc @@ -1,168 +1,59 @@ [[query-dsl-term-query]] === Term Query -The `term` query finds documents that contain the *exact* term specified -in the inverted index. For instance: +Returns documents that contain an *exact* term in a provided field. -[source,js] --------------------------------------------------- -POST _search -{ - "query": { - "term" : { "user" : "Kimchy" } <1> - } -} --------------------------------------------------- -// CONSOLE -<1> Finds documents which contain the exact term `Kimchy` in the inverted index - of the `user` field. - -A `boost` parameter can be specified to give this `term` query a higher -relevance score than another query, for instance: - -[source,js] --------------------------------------------------- -GET _search -{ - "query": { - "bool": { - "should": [ - { - "term": { - "status": { - "value": "urgent", - "boost": 2.0 <1> - } - } - }, - { - "term": { - "status": "normal" <2> - } - } - ] - } - } -} --------------------------------------------------- -// CONSOLE - -<1> The `urgent` query clause has a boost of `2.0`, meaning it is twice as important - as the query clause for `normal`. -<2> The `normal` clause has the default neutral boost of `1.0`. - -A `term` query can also match against <>. - -.Why doesn't the `term` query match my document? -************************************************** - -String fields can be of type `text` (treated as full text, like the body of an -email), or `keyword` (treated as exact values, like an email address or a -zip code). Exact values (like numbers, dates, and keywords) have -the exact value specified in the field added to the inverted index in order -to make them searchable. +You can use the `term` query to find documents based on a precise value such as +a price, a product ID, or a username. -However, `text` fields are `analyzed`. This means that their -values are first passed through an <> to produce a list of -terms, which are then added to the inverted index. +[WARNING] +==== +Avoid using the `term` query for <> fields. -There are many ways to analyze text: the default -<> drops most punctuation, -breaks up text into individual words, and lower cases them. For instance, -the `standard` analyzer would turn the string ``Quick Brown Fox!'' into the -terms [`quick`, `brown`, `fox`]. +By default, {es} changes the values of `text` fields as part of <>. This can make finding exact matches for `text` field values +difficult. -This analysis process makes it possible to search for individual words -within a big block of full text. +To search `text` field values, use the <> query +instead. +==== -The `term` query looks for the *exact* term in the field's inverted index -- -it doesn't know anything about the field's analyzer. This makes it useful for -looking up values in keyword fields, or in numeric or date -fields. When querying full text fields, use the -<> instead, which understands how the field -has been analyzed. - - -To demonstrate, try out the example below. First, create an index, specifying the field mappings, and index a document: +==== Example request [source,js] --------------------------------------------------- -PUT my_index -{ - "mappings": { - "properties": { - "full_text": { - "type": "text" <1> - }, - "exact_value": { - "type": "keyword" <2> - } +---- +GET /_search +{ + "query": { + "term": { + "user": { + "value": "Kimchy", + "boost": 1.0 + } + } } - } } - -PUT my_index/_doc/1 -{ - "full_text": "Quick Foxes!", <3> - "exact_value": "Quick Foxes!" <4> -} --------------------------------------------------- +---- // CONSOLE -<1> The `full_text` field is of type `text` and will be analyzed. -<2> The `exact_value` field is of type `keyword` and will NOT be analyzed. -<3> The `full_text` inverted index will contain the terms: [`quick`, `foxes`]. -<4> The `exact_value` inverted index will contain the exact term: [`Quick Foxes!`]. - -Now, compare the results for the `term` query and the `match` query: - -[source,js] --------------------------------------------------- -GET my_index/_search -{ - "query": { - "term": { - "exact_value": "Quick Foxes!" <1> - } - } -} - -GET my_index/_search -{ - "query": { - "term": { - "full_text": "Quick Foxes!" <2> - } - } -} - -GET my_index/_search -{ - "query": { - "term": { - "full_text": "foxes" <3> - } - } -} - -GET my_index/_search -{ - "query": { - "match": { - "full_text": "Quick Foxes!" <4> - } - } -} --------------------------------------------------- -// CONSOLE -// TEST[continued] +==== Top-level parameters for `term` +``:: +Field you wish to search. + +==== Parameters for `` +`value`:: +Term you wish to find in the provided ``. To return a document, the term +must exactly match the field value, including whitespace and capitalization. + +`boost`:: +Floating point number used to decrease or increase the +<> 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. -<1> This query matches because the `exact_value` field contains the exact - term `Quick Foxes!`. -<2> This query does not match, because the `full_text` field only contains - the terms `quick` and `foxes`. It does not contain the exact term - `Quick Foxes!`. -<3> A `term` query for the term `foxes` matches the `full_text` field. -<4> This `match` query on the `full_text` field first analyzes the query string, - then looks for documents containing `quick` or `foxes` or both. -************************************************** From d10254ad2179ff0c6f8312fc00a600313515a42c Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Mon, 29 Apr 2019 17:56:26 -0400 Subject: [PATCH 2/5] [DOCS] Add anchors to request example --- docs/reference/query-dsl/term-query.asciidoc | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/reference/query-dsl/term-query.asciidoc b/docs/reference/query-dsl/term-query.asciidoc index cdb7ac79308f4..0ca7bce6bd71d 100644 --- a/docs/reference/query-dsl/term-query.asciidoc +++ b/docs/reference/query-dsl/term-query.asciidoc @@ -18,6 +18,7 @@ To search `text` field values, use the <> query instead. ==== +[[term-query-ex-request]] ==== Example request [source,js] From ed44215a1aed9d92258eef4f44588f2badaa3b65 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Wed, 1 May 2019 18:12:12 -0400 Subject: [PATCH 3/5] [DOCS] Re-add term vs. match query example --- docs/reference/query-dsl/term-query.asciidoc | 150 +++++++++++++++++++ 1 file changed, 150 insertions(+) diff --git a/docs/reference/query-dsl/term-query.asciidoc b/docs/reference/query-dsl/term-query.asciidoc index 0ca7bce6bd71d..be8b34a4e6d8f 100644 --- a/docs/reference/query-dsl/term-query.asciidoc +++ b/docs/reference/query-dsl/term-query.asciidoc @@ -37,10 +37,12 @@ GET /_search ---- // CONSOLE +[[term-top-level-params]] ==== Top-level parameters for `term` ``:: Field you wish to search. +[[term-field-params]] ==== Parameters for `` `value`:: Term you wish to find in the provided ``. To return a document, the term @@ -58,3 +60,151 @@ 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 <> changes +`text` field values as follows: + +* Removes most punctuation +* Divides the remaining content into individual words, called +<> +* 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,js] +---- +PUT my_index +{ + "mappings" : { + "properties" : { + "full_text" : { "type" : "text" } + } + } +} +---- +// CONSOLE + +-- + +. Index a document with a value of `Quick Brown Foxes!` in the `full_text` +field. ++ +-- + +[source,js] +---- +PUT my_index/_doc/1 +{ + "full_text": "Quick Brown Foxes!" +} +---- +// CONSOLE +// 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,js] +---- +GET my_index/_search?pretty +{ + "query": { + "term": { + "full_text": "Quick Brown Foxes!" + } + } +} +---- +// CONSOLE +// 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,js] +---- +GET my_index/_search?pretty +{ + "query": { + "match": { + "full_text": "Quick Brown Foxes!" + } + } +} +---- +// CONSOLE +// 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,js] +---- +{ + "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/1/$body.took/] + +-- \ No newline at end of file From da9123a8bbaea13ddada8e804c0e0be427d29d16 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Wed, 1 May 2019 22:27:43 -0400 Subject: [PATCH 4/5] [DOCS] Fix //TESTRESPONSE Comment --- docs/reference/query-dsl/term-query.asciidoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/reference/query-dsl/term-query.asciidoc b/docs/reference/query-dsl/term-query.asciidoc index be8b34a4e6d8f..621c27a4e51dd 100644 --- a/docs/reference/query-dsl/term-query.asciidoc +++ b/docs/reference/query-dsl/term-query.asciidoc @@ -205,6 +205,5 @@ in the results. } } ---- -// TESTRESPONSE[s/1/$body.took/] - +// TESTRESPONSE[s/"took" : 1/"took" : $body.took/] -- \ No newline at end of file From 058ff63efcb4e987b1f4cff6725215fd9cb0c95b Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Mon, 6 May 2019 10:19:10 -0400 Subject: [PATCH 5/5] [DOCS] Add index refresh snippet in comments to pass gradle checks --- docs/reference/query-dsl/term-query.asciidoc | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/reference/query-dsl/term-query.asciidoc b/docs/reference/query-dsl/term-query.asciidoc index 621c27a4e51dd..25da70d0cf1e1 100644 --- a/docs/reference/query-dsl/term-query.asciidoc +++ b/docs/reference/query-dsl/term-query.asciidoc @@ -152,6 +152,17 @@ field. + -- +//// + +[source,js] +---- +POST my_index/_refresh +---- +// CONSOLE +// TEST[continued] + +//// + [source,js] ---- GET my_index/_search?pretty