249 lines
5.4 KiB
Plaintext
249 lines
5.4 KiB
Plaintext
[[query-dsl-terms-query]]
|
|
=== Terms query
|
|
++++
|
|
<titleabbrev>Terms</titleabbrev>
|
|
++++
|
|
|
|
Returns documents that contain one or more *exact* terms in a provided field.
|
|
|
|
The `terms` query is the same as the <<query-dsl-term-query, `term` query>>,
|
|
except you can search for multiple values.
|
|
|
|
[[terms-query-ex-request]]
|
|
==== Example request
|
|
|
|
The following search returns documents where the `user` field contains `kimchy`
|
|
or `elasticsearch`.
|
|
|
|
[source,console]
|
|
----
|
|
GET /_search
|
|
{
|
|
"query" : {
|
|
"terms" : {
|
|
"user" : ["kimchy", "elasticsearch"],
|
|
"boost" : 1.0
|
|
}
|
|
}
|
|
}
|
|
----
|
|
|
|
[[terms-top-level-params]]
|
|
==== Top-level parameters for `terms`
|
|
`<field>`::
|
|
+
|
|
--
|
|
(Optional, object) Field you wish to search.
|
|
|
|
The value of this parameter is an array of terms you wish to find in the
|
|
provided field. To return a document, one or more terms must exactly match a
|
|
field value, including whitespace and capitalization.
|
|
|
|
By default, {es} limits the `terms` query to a maximum of 65,536
|
|
terms. You can change this limit using the <<index-max-terms-count,
|
|
`index.max_terms_count`>> setting.
|
|
|
|
[NOTE]
|
|
To use the field values of an existing document as search terms, use the
|
|
<<query-dsl-terms-lookup, terms lookup>> parameters.
|
|
--
|
|
|
|
`boost`::
|
|
+
|
|
--
|
|
(Optional, float) Floating point number used to decrease or increase the
|
|
<<relevance-scores,relevance scores>> of a query. Defaults to `1.0`.
|
|
|
|
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.
|
|
--
|
|
|
|
[[terms-query-notes]]
|
|
==== Notes
|
|
|
|
[[query-dsl-terms-query-highlighting]]
|
|
===== Highlighting `terms` queries
|
|
<<request-body-search-highlighting,Highlighting>> is best-effort only. {es} may not
|
|
return highlight results for `terms` queries depending on:
|
|
|
|
* Highlighter type
|
|
* Number of terms in the query
|
|
|
|
[[query-dsl-terms-lookup]]
|
|
===== Terms lookup
|
|
Terms lookup fetches the field values of an existing document. {es} then uses
|
|
those values as search terms. This can be helpful when searching for a large set
|
|
of terms.
|
|
|
|
Because terms lookup fetches values from a document, the <<mapping-source-field,
|
|
`_source`>> mapping field must be enabled to use terms lookup. The `_source`
|
|
field is enabled by default.
|
|
|
|
[NOTE]
|
|
By default, {es} limits the `terms` query to a maximum of 65,536
|
|
terms. This includes terms fetched using terms lookup. You can change
|
|
this limit using the <<index-max-terms-count, `index.max_terms_count`>> setting.
|
|
|
|
To perform a terms lookup, use the following parameters.
|
|
|
|
[[query-dsl-terms-lookup-params]]
|
|
====== Terms lookup parameters
|
|
`index`::
|
|
(Optional, string) Name of the index from which to fetch field values.
|
|
|
|
`id`::
|
|
(Optional, string) <<mapping-id-field,ID>> of the document from which to fetch
|
|
field values.
|
|
|
|
`path`::
|
|
+
|
|
--
|
|
(Optional, string) Name of the field from which to fetch field values. {es} uses
|
|
these values as search terms for the query.
|
|
|
|
If the field values include an array of nested inner objects, you can access
|
|
those objects using dot notation syntax.
|
|
--
|
|
|
|
`routing`::
|
|
(Optional, string) Custom <<mapping-routing-field, routing value>> of the
|
|
document from which to fetch term values. If a custom routing value was provided
|
|
when the document was indexed, this parameter is required.
|
|
|
|
[[query-dsl-terms-lookup-example]]
|
|
====== Terms lookup example
|
|
|
|
To see how terms lookup works, try the following example.
|
|
|
|
. Create an index with a `keyword` field named `color`.
|
|
+
|
|
--
|
|
|
|
[source,console]
|
|
----
|
|
PUT my_index
|
|
{
|
|
"mappings" : {
|
|
"properties" : {
|
|
"color" : { "type" : "keyword" }
|
|
}
|
|
}
|
|
}
|
|
----
|
|
--
|
|
|
|
. Index a document with an ID of 1 and values of `["blue", "green"]` in the
|
|
`color` field.
|
|
+
|
|
--
|
|
|
|
[source,console]
|
|
----
|
|
PUT my_index/_doc/1
|
|
{
|
|
"color": ["blue", "green"]
|
|
}
|
|
----
|
|
// TEST[continued]
|
|
--
|
|
|
|
. Index another document with an ID of 2 and value of `blue` in the `color`
|
|
field.
|
|
+
|
|
--
|
|
|
|
[source,console]
|
|
----
|
|
PUT my_index/_doc/2
|
|
{
|
|
"color": "blue"
|
|
}
|
|
----
|
|
// TEST[continued]
|
|
--
|
|
|
|
. Use the `terms` query with terms lookup parameters to find documents
|
|
containing one or more of the same terms as document 2. Include the `pretty`
|
|
parameter so the response is more readable.
|
|
+
|
|
--
|
|
|
|
////
|
|
|
|
[source,console]
|
|
----
|
|
POST my_index/_refresh
|
|
----
|
|
// TEST[continued]
|
|
|
|
////
|
|
|
|
[source,console]
|
|
----
|
|
GET my_index/_search?pretty
|
|
{
|
|
"query": {
|
|
"terms": {
|
|
"color" : {
|
|
"index" : "my_index",
|
|
"id" : "2",
|
|
"path" : "color"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
----
|
|
// TEST[continued]
|
|
|
|
Because document 2 and document 1 both contain `blue` as a value in the `color`
|
|
field, {es} returns both documents.
|
|
|
|
[source,console-result]
|
|
----
|
|
{
|
|
"took" : 17,
|
|
"timed_out" : false,
|
|
"_shards" : {
|
|
"total" : 1,
|
|
"successful" : 1,
|
|
"skipped" : 0,
|
|
"failed" : 0
|
|
},
|
|
"hits" : {
|
|
"total" : {
|
|
"value" : 2,
|
|
"relation" : "eq"
|
|
},
|
|
"max_score" : 1.0,
|
|
"hits" : [
|
|
{
|
|
"_index" : "my_index",
|
|
"_type" : "_doc",
|
|
"_id" : "1",
|
|
"_score" : 1.0,
|
|
"_source" : {
|
|
"color" : [
|
|
"blue",
|
|
"green"
|
|
]
|
|
}
|
|
},
|
|
{
|
|
"_index" : "my_index",
|
|
"_type" : "_doc",
|
|
"_id" : "2",
|
|
"_score" : 1.0,
|
|
"_source" : {
|
|
"color" : "blue"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
}
|
|
----
|
|
// TESTRESPONSE[s/"took" : 17/"took" : $body.took/]
|
|
-- |