Skip to content

Commit 5738ba3

Browse files
jrodewigjrodewig
committed
[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
1 parent 0946e08 commit 5738ba3

File tree

1 file changed

+44
-153
lines changed

1 file changed

+44
-153
lines changed

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

Lines changed: 44 additions & 153 deletions
Original file line numberDiff line numberDiff line change
@@ -1,168 +1,59 @@
11
[[query-dsl-term-query]]
22
=== Term Query
33

4-
The `term` query finds documents that contain the *exact* term specified
5-
in the inverted index. For instance:
4+
Returns documents that contain an *exact* term in a provided field.
65

7-
[source,js]
8-
--------------------------------------------------
9-
POST _search
10-
{
11-
"query": {
12-
"term" : { "user" : "Kimchy" } <1>
13-
}
14-
}
15-
--------------------------------------------------
16-
// CONSOLE
17-
<1> Finds documents which contain the exact term `Kimchy` in the inverted index
18-
of the `user` field.
19-
20-
A `boost` parameter can be specified to give this `term` query a higher
21-
relevance score than another query, for instance:
22-
23-
[source,js]
24-
--------------------------------------------------
25-
GET _search
26-
{
27-
"query": {
28-
"bool": {
29-
"should": [
30-
{
31-
"term": {
32-
"status": {
33-
"value": "urgent",
34-
"boost": 2.0 <1>
35-
}
36-
}
37-
},
38-
{
39-
"term": {
40-
"status": "normal" <2>
41-
}
42-
}
43-
]
44-
}
45-
}
46-
}
47-
--------------------------------------------------
48-
// CONSOLE
49-
50-
<1> The `urgent` query clause has a boost of `2.0`, meaning it is twice as important
51-
as the query clause for `normal`.
52-
<2> The `normal` clause has the default neutral boost of `1.0`.
53-
54-
A `term` query can also match against <<range, range data types>>.
55-
56-
.Why doesn't the `term` query match my document?
57-
**************************************************
58-
59-
String fields can be of type `text` (treated as full text, like the body of an
60-
email), or `keyword` (treated as exact values, like an email address or a
61-
zip code). Exact values (like numbers, dates, and keywords) have
62-
the exact value specified in the field added to the inverted index in order
63-
to make them searchable.
6+
You can use the `term` query to find documents based on a precise value such as
7+
a price, a product ID, or a username.
648

65-
However, `text` fields are `analyzed`. This means that their
66-
values are first passed through an <<analysis,analyzer>> to produce a list of
67-
terms, which are then added to the inverted index.
9+
[WARNING]
10+
====
11+
Avoid using the `term` query for <<text, `text`>> fields.
6812
69-
There are many ways to analyze text: the default
70-
<<analysis-standard-analyzer,`standard` analyzer>> drops most punctuation,
71-
breaks up text into individual words, and lower cases them. For instance,
72-
the `standard` analyzer would turn the string ``Quick Brown Fox!'' into the
73-
terms [`quick`, `brown`, `fox`].
13+
By default, {es} changes the values of `text` fields as part of <<analysis,
14+
analysis>>. This can make finding exact matches for `text` field values
15+
difficult.
7416
75-
This analysis process makes it possible to search for individual words
76-
within a big block of full text.
17+
To search `text` field values, use the <<query-dsl-match-query,`match`>> query
18+
instead.
19+
====
7720

78-
The `term` query looks for the *exact* term in the field's inverted index --
79-
it doesn't know anything about the field's analyzer. This makes it useful for
80-
looking up values in keyword fields, or in numeric or date
81-
fields. When querying full text fields, use the
82-
<<query-dsl-match-query,`match` query>> instead, which understands how the field
83-
has been analyzed.
84-
85-
86-
To demonstrate, try out the example below. First, create an index, specifying the field mappings, and index a document:
21+
==== Example request
8722

8823
[source,js]
89-
--------------------------------------------------
90-
PUT my_index
91-
{
92-
"mappings": {
93-
"properties": {
94-
"full_text": {
95-
"type": "text" <1>
96-
},
97-
"exact_value": {
98-
"type": "keyword" <2>
99-
}
24+
----
25+
GET /_search
26+
{
27+
"query": {
28+
"term": {
29+
"user": {
30+
"value": "Kimchy",
31+
"boost": 1.0
32+
}
33+
}
10034
}
101-
}
10235
}
103-
104-
PUT my_index/_doc/1
105-
{
106-
"full_text": "Quick Foxes!", <3>
107-
"exact_value": "Quick Foxes!" <4>
108-
}
109-
--------------------------------------------------
36+
----
11037
// CONSOLE
11138

112-
<1> The `full_text` field is of type `text` and will be analyzed.
113-
<2> The `exact_value` field is of type `keyword` and will NOT be analyzed.
114-
<3> The `full_text` inverted index will contain the terms: [`quick`, `foxes`].
115-
<4> The `exact_value` inverted index will contain the exact term: [`Quick Foxes!`].
116-
117-
Now, compare the results for the `term` query and the `match` query:
118-
119-
[source,js]
120-
--------------------------------------------------
121-
GET my_index/_search
122-
{
123-
"query": {
124-
"term": {
125-
"exact_value": "Quick Foxes!" <1>
126-
}
127-
}
128-
}
129-
130-
GET my_index/_search
131-
{
132-
"query": {
133-
"term": {
134-
"full_text": "Quick Foxes!" <2>
135-
}
136-
}
137-
}
138-
139-
GET my_index/_search
140-
{
141-
"query": {
142-
"term": {
143-
"full_text": "foxes" <3>
144-
}
145-
}
146-
}
147-
148-
GET my_index/_search
149-
{
150-
"query": {
151-
"match": {
152-
"full_text": "Quick Foxes!" <4>
153-
}
154-
}
155-
}
156-
--------------------------------------------------
157-
// CONSOLE
158-
// TEST[continued]
39+
==== Top-level parameters for `term`
40+
`<field>`::
41+
Field you wish to search.
42+
43+
==== Parameters for `<field>`
44+
`value`::
45+
Term you wish to find in the provided `<field>`. To return a document, the term
46+
must exactly match the field value, including whitespace and capitalization.
47+
48+
`boost`::
49+
Floating point number used to decrease or increase the
50+
<<query-filter-context, relevance scores>> of a query. Default is `1.0`.
51+
Optional.
52+
+
53+
You can use the `boost` parameter to adjust relevance scores for searches
54+
containing two or more queries.
55+
+
56+
Boost values are relative to the default value of `1.0`. A boost value between
57+
`0` and `1.0` decreases the relevance score. A value greater than `1.0`
58+
increases the relevance score.
15959

160-
<1> This query matches because the `exact_value` field contains the exact
161-
term `Quick Foxes!`.
162-
<2> This query does not match, because the `full_text` field only contains
163-
the terms `quick` and `foxes`. It does not contain the exact term
164-
`Quick Foxes!`.
165-
<3> A `term` query for the term `foxes` matches the `full_text` field.
166-
<4> This `match` query on the `full_text` field first analyzes the query string,
167-
then looks for documents containing `quick` or `foxes` or both.
168-
**************************************************

0 commit comments

Comments
 (0)