169 lines
4.6 KiB
Plaintext
169 lines
4.6 KiB
Plaintext
[[query-dsl-term-query]]
|
|
=== Term Query
|
|
|
|
The `term` query finds documents that contain the *exact* term specified
|
|
in the inverted index. For instance:
|
|
|
|
[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 <<range, range data types>>.
|
|
|
|
.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.
|
|
|
|
However, `text` fields are `analyzed`. This means that their
|
|
values are first passed through an <<analysis,analyzer>> to produce a list of
|
|
terms, which are then added to the inverted index.
|
|
|
|
There are many ways to analyze text: the default
|
|
<<analysis-standard-analyzer,`standard` analyzer>> 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`].
|
|
|
|
This analysis process makes it possible to search for individual words
|
|
within a big block of full text.
|
|
|
|
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
|
|
<<query-dsl-match-query,`match` query>> 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:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
PUT my_index
|
|
{
|
|
"mappings": {
|
|
"properties": {
|
|
"full_text": {
|
|
"type": "text" <1>
|
|
},
|
|
"exact_value": {
|
|
"type": "keyword" <2>
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
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]
|
|
|
|
<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.
|
|
**************************************************
|