[DOCS] Rewrite term query docs for new format
#41498
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,168 +1,220 @@ | ||
| [[query-dsl-term-query]] | ||
| === Term Query | ||
|
|
||
| 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,js] | ||
| ---- | ||
| GET /_search | ||
| { | ||
| "query": { | ||
| "term": { | ||
| "user": { | ||
| "value": "Kimchy", | ||
| "boost": 1.0 | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ---- | ||
| // CONSOLE | ||
|
|
||
| [[term-top-level-params]] | ||
| ==== Top-level parameters for `term` | ||
| `<field>`:: | ||
| Field you wish to search. | ||
|
|
||
| [[term-field-params]] | ||
| ==== Parameters for `<field>` | ||
| `value`:: | ||
| 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`:: | ||
| 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. | ||
|
|
||
| [[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,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. | ||
|
|
||
| -- | ||
|
|
||
|
There was a problem hiding this comment. Just out of curiosity: are there follow up plans to move these more detailed examples somewhere else? While I like the idea of having succinct, standardized docs for each query, I find these kind of examples quite useful and better to understand than merely the minimal snippet that remains. Not saying this shouldn't go away, I'm just curious what the plan is for examples like this in this rewriting effort. There was a problem hiding this comment. Thanks for the feedback @cbuescher. For this particular set of examples, I think a concept-focused page like "Search structured data" or "Search full-text" would be a better fit. Those pages don't exist yet, but I'll work on creating them and add it to this PR. For other queries, I think we can include additional sections for detailed examples below parameter documentation. A good example of this would be the Let me know if you feel differently. I'm still new so there could be context I'm missing. |
||
| . 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] | ||
| ---- | ||
| POST my_index/_refresh | ||
| ---- | ||
| // CONSOLE | ||
| // TEST[continued] | ||
|
|
||
| //// | ||
|
|
||
| [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/"took" : 1/"took" : $body.took/] | ||
| -- | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Whilst I'm not wedded to having this explanation in this page of the documentation I think it would be useful to make sure we explain the differece between searching with analyzed or not analyzed queries somewhere since it gives some understanding into how search works and how to avoid some pitfalls. wdyt?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for the feedback.
I think the warning provides enough information for users looking to get started quickly, but it doesn't explain why you should avoid using term-level queries for analyzed fields. The example in the aside is great for that.
I think that content would fit better in a concept-focused page like "Search structured data" or "Search full-text." Those don't exist yet, but I'll work on creating them and add it to this PR.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That sounds great, thanks