« Regexp queryTerms query »
Elastic Docs›Elasticsearch Guide [8.15]›Query DSL›Term-level queries
Returns documents that contain an exact term in a provided field.
You can use the term query to find documents based on a precise value such asa price, a product ID, or a username.
Avoid using the term query for text fields.
By default, Elasticsearch changes the values of text fields as part of analysis. This can make finding exact matches for text field valuesdifficult.
To search text field values, use the match queryinstead.
resp = client.search( query={ "term": { "user.id": { "value": "kimchy", "boost": 1 } } },)print(resp)response = client.search( body: { query: { term: { 'user.id' => { value: 'kimchy', boost: 1 } } } })puts responseconst response = await client.search({ query: { term: { "user.id": { value: "kimchy", boost: 1, }, }, },});console.log(response);GET /_search{ "query": { "term": { "user.id": { "value": "kimchy", "boost": 1.0 } } }}value- (Required, string) Term you wish to find in the provided
<field>. To return adocument, the term must exactly match the field value, including whitespace andcapitalization. boost(Optional, float) Floating point number used to decrease or increase therelevance scores of a query. Defaults to
1.0.You can use the
boostparameter to adjust relevance scores for searchescontaining two or more queries.Boost values are relative to the default value of
1.0. A boost value between0and1.0decreases the relevance score. A value greater than1.0increases the relevance score.case_insensitive[7.10.0]Added in 7.10.0.- (Optional, Boolean) Allows ASCII case insensitive matching of thevalue with the indexed field values when set to true. Default is false which meansthe case sensitivity of matching depends on the underlying field’s mapping.
By default, Elasticsearch changes the values of text fields during analysis. Forexample, the default standard analyzer changestext field values as follows:
- Removes most punctuation
- Divides the remaining content into individual words, calledtokens
- Lowercases the tokens
To better search text fields, the match query also analyzes your providedsearch term before performing a search. This means the match query can searchtext fields for analyzed tokens rather than an exact term.
The term query does not analyze the search term. The term query onlysearches for the exact term you provide. This means the term query mayreturn poor or no results when searching text fields.
To see the difference in search results, try the following example.
Create an index with a
textfield calledfull_text.resp = client.indices.create( index="my-index-000001", mappings={ "properties": { "full_text": { "type": "text" } } },)print(resp)response = client.indices.create( index: 'my-index-000001', body: { mappings: { properties: { full_text: { type: 'text' } } } })puts responseres, err := es.Indices.Create("my-index-000001",es.Indices.Create.WithBody(strings.NewReader(`{ "mappings": { "properties": { "full_text": { "type": "text" } } }}`)),)fmt.Println(res, err)const response = await client.indices.create({ index: "my-index-000001", mappings: { properties: { full_text: { type: "text", }, }, },});console.log(response);PUT my-index-000001{ "mappings": { "properties": { "full_text": { "type": "text" } } }}Index a document with a value of
Quick Brown Foxes!in thefull_textfield.resp = client.index( index="my-index-000001", id="1", document={ "full_text": "Quick Brown Foxes!" },)print(resp)response = client.index( index: 'my-index-000001', id: 1, body: { full_text: 'Quick Brown Foxes!' })puts responseres, err := es.Index("my-index-000001",strings.NewReader(`{ "full_text": "Quick Brown Foxes!"}`),es.Index.WithDocumentID("1"),es.Index.WithPretty(),)fmt.Println(res, err)const response = await client.index({ index: "my-index-000001", id: 1, document: { full_text: "Quick Brown Foxes!", },});console.log(response);PUT my-index-000001/_doc/1{ "full_text": "Quick Brown Foxes!"}Because
full_textis atextfield, Elasticsearch changesQuick Brown Foxes!to[quick, brown, fox]during analysis.Use the
termquery to search forQuick Brown Foxes!in thefull_textfield. Include theprettyparameter so the response is more readable.resp = client.search( index="my-index-000001", pretty=True, query={ "term": { "full_text": "Quick Brown Foxes!" } },)print(resp)response = client.search( index: 'my-index-000001', pretty: true, body: { query: { term: { full_text: 'Quick Brown Foxes!' } } })puts responseres, err := es.Search(es.Search.WithIndex("my-index-000001"),es.Search.WithBody(strings.NewReader(`{ "query": { "term": { "full_text": "Quick Brown Foxes!" } }}`)),es.Search.WithPretty(),)fmt.Println(res, err)const response = await client.search({ index: "my-index-000001", pretty: "true", query: { term: { full_text: "Quick Brown Foxes!", }, },});console.log(response);GET my-index-000001/_search?pretty{ "query": { "term": { "full_text": "Quick Brown Foxes!" } }}Because the
full_textfield no longer contains the exact termQuick BrownFoxes!, thetermquery search returns no results.Use the
matchquery to search forQuick Brown Foxes!in thefull_textfield.resp = client.search( index="my-index-000001", pretty=True, query={ "match": { "full_text": "Quick Brown Foxes!" } },)print(resp)response = client.search( index: 'my-index-000001', pretty: true, body: { query: { match: { full_text: 'Quick Brown Foxes!' } } })puts responseres, err := es.Search(es.Search.WithIndex("my-index-000001"),es.Search.WithBody(strings.NewReader(`{ "query": { "match": { "full_text": "Quick Brown Foxes!" } }}`)),es.Search.WithPretty(),)fmt.Println(res, err)const response = await client.search({ index: "my-index-000001", pretty: "true", query: { match: { full_text: "Quick Brown Foxes!", }, },});console.log(response);GET my-index-000001/_search?pretty{ "query": { "match": { "full_text": "Quick Brown Foxes!" } }}Unlike the
termquery, thematchquery analyzes your provided search term,Quick Brown Foxes!, before performing a search. Thematchquery then returnsany documents containing thequick,brown, orfoxtokens in thefull_textfield.Here’s the response for the
matchquery search containing the indexed documentin the results.{ "took" : 1, "timed_out" : false, "_shards" : { "total" : 1, "successful" : 1, "skipped" : 0, "failed" : 0 }, "hits" : { "total" : { "value" : 1, "relation" : "eq" }, "max_score" : 0.8630463, "hits" : [ { "_index" : "my-index-000001", "_id" : "1", "_score" : 0.8630463, "_source" : { "full_text" : "Quick Brown Foxes!" } } ] }}
« Regexp queryTerms query »
Most Popular
Video
Get Started with ElasticsearchVideo
Intro to KibanaVideo
![Term query | Elasticsearch Guide [8.15] (2024)](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/h8AAvMB+NzmkbcAAAAASUVORK5CYII=)