IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Regexp query Terms query »
Elastic Docs ›Elasticsearch Guide [7.8] ›Query DSL ›Term-level queries

Term query

edit

Term query

edit

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 as a 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 values difficult.

To search text field values, use the match query instead.

Example request

edit
GET /_search
{
  "query": {
    "term": {
      "user.id": {
        "value": "kimchy",
        "boost": 1.0
      }
    }
  }
}

Top-level parameters for term

edit
<field>
(Required, object) Field you wish to search.

Parameters for <field>

edit
value
(Required, string) Term you wish to find in the provided <field>. To return a document, the term must exactly match the field value, including whitespace and capitalization.
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 between 0 and 1.0 decreases the relevance score. A value greater than 1.0 increases the relevance score.

Notes

edit

Avoid using the term query for text fields

edit

By default, Elasticsearch changes the values of text fields during analysis. For example, the default standard analyzer changes text field values as follows:

  • Removes most punctuation
  • Divides the remaining content into individual words, called tokens
  • Lowercases the tokens

To better search text fields, the match query also analyzes your provided search term before performing a search. This means the match query can search text fields for analyzed tokens rather than an exact term.

The term query does not analyze the search term. The term query only searches for the exact term you provide. This means the term query may return poor or no results when searching text fields.

To see the difference in search results, try the following example.

  1. Create an index with a text field called full_text.

    PUT my-index-000001
{
  "mappings": {
    "properties": {
      "full_text": { "type": "text" }
    }
  }
}

  2. Index a document with a value of Quick Brown Foxes! in the full_text field.

    PUT my-index-000001/_doc/1
{
  "full_text":   "Quick Brown Foxes!"
}

    Because full_text is a text field, Elasticsearch changes Quick Brown Foxes! to [quick, brown, fox] during analysis.

  3. Use the term query to search for Quick Brown Foxes! in the full_text field. Include the pretty parameter so the response is more readable.

    GET my-index-000001/_search?pretty
{
  "query": {
    "term": {
      "full_text": "Quick Brown Foxes!"
    }
  }
}

    Because the full_text field no longer contains the exact term Quick Brown Foxes!, the term query search returns no results.

  4. Use the match query to search for Quick Brown Foxes! in the full_text field.

    GET my-index-000001/_search?pretty
{
  "query": {
    "match": {
      "full_text": "Quick Brown Foxes!"
    }
  }
}

    Unlike the term query, the match query analyzes your provided search term, Quick Brown Foxes!, before performing a search. The match query then returns any documents containing the quick, brown, or fox tokens in the full_text field.

    Here’s the response for the match query search containing the indexed document in 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",
        "_type" : "_doc",
        "_id" : "1",
        "_score" : 0.8630463,
        "_source" : {
          "full_text" : "Quick Brown Foxes!"
        }
      }
    ]
  }
}
« Regexp query Terms query »