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

Terms query

edit

Terms query

edit

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

edit

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

resp = client.search(
    body={
        "query": {"terms": {"user.id": ["kimchy", "elkbee"], "boost": 1}}
    },
)
print(resp)
response = client.search(
  body: {
    query: {
      terms: {
        'user.id' => [
          'kimchy',
          'elkbee'
        ],
        boost: 1
      }
    }
  }
)
puts 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 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

edit

Highlighting terms queries

edit

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

edit

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.

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
edit

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

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

    resp = client.indices.create(
    index="my-index-000001",
    body={"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)
    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.

    resp = client.index(
    index="my-index-000001",
    id="1",
    body={"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)
    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.

    resp = client.index(
    index="my-index-000001",
    id="2",
    body={"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)
    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.

    resp = client.search(
    index="my-index-000001",
    pretty=True,
    body={
        "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)
    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",
        "_id" : "1",
        "_score" : 1.0,
        "_source" : {
          "color" : [
            "blue",
            "green"
          ]
        }
      },
      {
        "_index" : "my-index-000001",
        "_id" : "2",
        "_score" : 1.0,
        "_source" : {
          "color" : "blue"
        }
      }
    ]
  }
}
« Term query Terms set query »