Terms query

Returns 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

The following search returns documents where the user.id field contains kimchy or elkbee.

GET /_search
{
  "query": {
    "terms": {
      "user.id": [ "kimchy", "elkbee" ],
      "boost": 1.0
    }
  }
}

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, Elasticsearch limits the terms query to a maximum of 65,536 terms. You can change this limit using the index.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 between 0 and 1.0 decreases the relevance score. A value greater than 1.0 increases the relevance score.

Notes

Highlighting terms queries

Highlighting 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

Terms 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

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

To see how terms lookup works, try the following example.

1. Create an index with a keyword field named color.

   PUT my-index-000001
   {
     "mappings": {
       "properties": {
         "color": { "type": "keyword" }
       }
     }
   }

2. Index a document with an ID of 1 and values of ["blue", "green"] in the color field.

   PUT my-index-000001/_doc/1
   {
     "color":   ["blue", "green"]
   }

3. Index another document with an ID of 2 and value of blue in the color field.

   PUT my-index-000001/_doc/2
   {
     "color":   "blue"
   }

4. 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.

   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 the color 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",
           "_type" : "_doc",
           "_id" : "1",
           "_score" : 1.0,
           "_source" : {
             "color" : [
               "blue",
               "green"
             ]
           }
         },
         {
           "_index" : "my-index-000001",
           "_type" : "_doc",
           "_id" : "2",
           "_score" : 1.0,
           "_source" : {
             "color" : "blue"
           }
         }
       ]
     }
   }