Terms query
editTerms query
editReturns documents that contain one or more exact terms in a provided field.
The terms
query is the same as the term
query,
except you can search for multiple values.
Example request
editThe following search returns documents where the user
field contains kimchy
or elasticsearch
.
GET /_search { "query" : { "terms" : { "user" : ["kimchy", "elasticsearch"], "boost" : 1.0 } } }
Top-level parameters for terms
edit-
<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, Elasticsearch limits the
terms
query to a maximum of 65,536 terms. You can change this limit using theindex.max_terms_count
setting.To use the field values of an existing document as search terms, use the terms lookup parameters.
-
boost
-
(Optional, float) Floating point number used to decrease or increase the 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 between0
and1.0
decreases the relevance score. A value greater than1.0
increases the relevance score.
Notes
editHighlighting terms
queries
editHighlighting is best-effort only. Elasticsearch may not
return highlight results for terms
queries depending on:
- Highlighter type
- Number of terms in the query
Terms lookup
editTerms lookup fetches the field values of an existing document. Elasticsearch 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 _source
mapping field must be enabled to use terms lookup. The _source
field is enabled by default.
By default, Elasticsearch 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
setting.
To perform a terms lookup, use the following parameters.
Terms lookup parameters
edit-
index
- (Optional, string) Name of the index from which to fetch field values.
-
id
- (Optional, string) ID of the document from which to fetch field values.
-
path
-
(Optional, string) Name of the field from which to fetch field values. Elasticsearch 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 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.
Terms lookup example
editTo see how terms lookup works, try the following example.
-
Create an index with a
keyword
field namedcolor
.PUT my_index { "mappings" : { "properties" : { "color" : { "type" : "keyword" } } } }
-
Index a document with an ID of 1 and values of
["blue", "green"]
in thecolor
field.PUT my_index/_doc/1 { "color": ["blue", "green"] }
-
Index another document with an ID of 2 and value of
blue
in thecolor
field.PUT my_index/_doc/2 { "color": "blue" }
-
Use the
terms
query with terms lookup parameters to find documents containing one or more of the same terms as document 2. Include thepretty
parameter so the response is more readable.GET my_index/_search?pretty { "query": { "terms": { "color" : { "index" : "my_index", "id" : "2", "path" : "color" } } } }
Because document 2 and document 1 both contain
blue
as a value in thecolor
field, Elasticsearch returns both documents.{ "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" } } ] } }