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. A document will match if it contains
at least one of the terms. To search for documents that contain more than one
matching term, use the terms_set
query.
Example request
editThe following search returns documents where the user.id
field contains kimchy
or elkbee
.
resp = client.search( query={ "terms": { "user.id": [ "kimchy", "elkbee" ], "boost": 1 } }, ) print(resp)
response = client.search( body: { query: { terms: { 'user.id' => [ 'kimchy', 'elkbee' ], boost: 1 } } } ) puts response
const response = await client.search({ query: { terms: { "user.id": ["kimchy", "elkbee"], boost: 1, }, }, }); console.log(response);
GET /_search { "query": { "terms": { "user.id": [ "kimchy", "elkbee" ], "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.
To run a terms lookup, the field’s _source
must be
enabled. You cannot use cross-cluster search to run a terms lookup on a remote index.
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 reduce network traffic, a terms lookup will fetch the document’s values from a shard on a local data node if possible. If the your terms data is not large, consider using an index with a single primary shard that’s fully replicated across all applicable data nodes to minimize network traffic.
To perform a terms lookup, use the following parameters.
Terms lookup parameters
edit-
index
- (Required, string) Name of the index from which to fetch field values.
-
id
- (Required, string) ID of the document from which to fetch field values.
-
path
-
(Required, 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
.resp = client.indices.create( index="my-index-000001", mappings={ "properties": { "color": { "type": "keyword" } } }, ) print(resp)
response = client.indices.create( index: 'my-index-000001', body: { mappings: { properties: { color: { type: 'keyword' } } } } ) puts response
res, err := es.Indices.Create( "my-index-000001", es.Indices.Create.WithBody(strings.NewReader(`{ "mappings": { "properties": { "color": { "type": "keyword" } } } }`)), ) fmt.Println(res, err)
const response = await client.indices.create({ index: "my-index-000001", mappings: { properties: { color: { type: "keyword", }, }, }, }); console.log(response);
PUT my-index-000001 { "mappings": { "properties": { "color": { "type": "keyword" } } } }
-
Index a document with an ID of 1 and values of
["blue", "green"]
in thecolor
field.resp = client.index( index="my-index-000001", id="1", document={ "color": [ "blue", "green" ] }, ) print(resp)
response = client.index( index: 'my-index-000001', id: 1, body: { color: [ 'blue', 'green' ] } ) puts response
res, err := es.Index( "my-index-000001", strings.NewReader(`{ "color": [ "blue", "green" ] }`), es.Index.WithDocumentID("1"), es.Index.WithPretty(), ) fmt.Println(res, err)
const response = await client.index({ index: "my-index-000001", id: 1, document: { color: ["blue", "green"], }, }); console.log(response);
PUT my-index-000001/_doc/1 { "color": ["blue", "green"] }
-
Index another document with an ID of 2 and value of
blue
in thecolor
field.resp = client.index( index="my-index-000001", id="2", document={ "color": "blue" }, ) print(resp)
response = client.index( index: 'my-index-000001', id: 2, body: { color: 'blue' } ) puts response
res, err := es.Index( "my-index-000001", strings.NewReader(`{ "color": "blue" }`), es.Index.WithDocumentID("2"), es.Index.WithPretty(), ) fmt.Println(res, err)
const response = await client.index({ index: "my-index-000001", id: 2, document: { color: "blue", }, }); console.log(response);
PUT my-index-000001/_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.resp = client.search( index="my-index-000001", pretty=True, query={ "terms": { "color": { "index": "my-index-000001", "id": "2", "path": "color" } } }, ) print(resp)
response = client.search( index: 'my-index-000001', pretty: true, body: { query: { terms: { color: { index: 'my-index-000001', id: '2', path: 'color' } } } } ) puts response
res, err := es.Search( es.Search.WithIndex("my-index-000001"), es.Search.WithBody(strings.NewReader(`{ "query": { "terms": { "color": { "index": "my-index-000001", "id": "2", "path": "color" } } } }`)), es.Search.WithPretty(), ) fmt.Println(res, err)
const response = await client.search({ index: "my-index-000001", pretty: "true", query: { terms: { color: { index: "my-index-000001", id: "2", path: "color", }, }, }, }); console.log(response);
GET my-index-000001/_search?pretty { "query": { "terms": { "color" : { "index" : "my-index-000001", "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-000001", "_id" : "1", "_score" : 1.0, "_source" : { "color" : [ "blue", "green" ] } }, { "_index" : "my-index-000001", "_id" : "2", "_score" : 1.0, "_source" : { "color" : "blue" } } ] } }