Terms query

Use the terms query to search for multiple terms in the same field. For example, the following query searches for lines with the IDs 61809 and 61810:

  1. GET shakespeare/_search
  2. {
  3. "query": {
  4. "terms": {
  5. "line_id": [
  6. "61809",
  7. "61810"
  8. ]
  9. }
  10. }
  11. }

copy

A document is returned if it matches any of the terms in the array.

By default, the maximum number of terms allowed in a terms query is 65,536. To change the maximum number of terms, update the index.max_terms_count setting.

The ability to highlight results for terms queries may not be guaranteed, depending on the highlighter type and the number of terms in the query.

Parameters

The query accepts the following parameters. All parameters are optional.

ParameterData typeDescription
<field>StringThe field in which to search. A document is returned in the results only if its field value exactly matches at least one term, with the correct spacing and capitalization.
boostFloating-pointBoosts the query by the given multiplier. Useful for searches that contain more than one query. Values in the [0, 1) range decrease relevance, and values greater than 1 increase relevance. Default is 1.

Terms lookup

Terms lookup retrieves the field values of a single document and uses them as search terms. You can use terms lookup to search for a large number of terms.

To use terms lookup, you must enable the _source mapping field because terms lookup fetches values from a document. The _source field is enabled by default.

Terms lookup tries to fetch the document field values from a shard on a local data node. Thus, using an index with a single primary shard that has full replicas on all applicable data nodes reduces network traffic.

Example

As an example, create an index that contains student data, mapping student_id as a keyword:

  1. PUT students
  2. {
  3. "mappings": {
  4. "properties": {
  5. "student_id": { "type": "keyword" }
  6. }
  7. }
  8. }

copy

Next, index three documents that correspond to students:

  1. PUT students/_doc/1
  2. {
  3. "name": "Jane Doe",
  4. "student_id" : "111"
  5. }

copy

  1. PUT students/_doc/2
  2. {
  3. "name": "Mary Major",
  4. "student_id" : "222"
  5. }

copy

  1. PUT students/_doc/3
  2. {
  3. "name": "John Doe",
  4. "student_id" : "333"
  5. }

copy

Create a separate index that contains class information, including the class name and an array of student IDs corresponding to the students enrolled in the class:

  1. PUT classes/_doc/101
  2. {
  3. "name": "CS101",
  4. "enrolled" : ["111" , "222"]
  5. }

copy

To search for students enrolled in the CS101 class, specify the document ID of the document that corresponds to the class, the index of that document, and the path of the field in which the terms are located:

  1. GET students/_search
  2. {
  3. "query": {
  4. "terms": {
  5. "student_id": {
  6. "index": "classes",
  7. "id": "101",
  8. "path": "enrolled"
  9. }
  10. }
  11. }
  12. }

copy

The response contains the documents in the students index for every student whose ID matches one of the values in the enrolled array:

  1. {
  2. "took": 13,
  3. "timed_out": false,
  4. "_shards": {
  5. "total": 1,
  6. "successful": 1,
  7. "skipped": 0,
  8. "failed": 0
  9. },
  10. "hits": {
  11. "total": {
  12. "value": 2,
  13. "relation": "eq"
  14. },
  15. "max_score": 1,
  16. "hits": [
  17. {
  18. "_index": "students",
  19. "_id": "1",
  20. "_score": 1,
  21. "_source": {
  22. "name": "Jane Doe",
  23. "student_id": "111"
  24. }
  25. },
  26. {
  27. "_index": "students",
  28. "_id": "2",
  29. "_score": 1,
  30. "_source": {
  31. "name": "Mary Major",
  32. "student_id": "222"
  33. }
  34. }
  35. ]
  36. }
  37. }

Example: Nested fields

The second example demonstrates querying nested fields. Consider an index with the following document:

  1. PUT classes/_doc/102
  2. {
  3. "name": "CS102",
  4. "enrolled_students" : {
  5. "id_list" : ["111" , "333"]
  6. }
  7. }

copy

To search for students enrolled in CS102, use the dot path notation to specify the full path to the field in the path parameter:

  1. ET students/_search
  2. {
  3. "query": {
  4. "terms": {
  5. "student_id": {
  6. "index": "classes",
  7. "id": "102",
  8. "path": "enrolled_students.id_list"
  9. }
  10. }
  11. }
  12. }

copy

The response contains the matching documents:

  1. {
  2. "took": 18,
  3. "timed_out": false,
  4. "_shards": {
  5. "total": 1,
  6. "successful": 1,
  7. "skipped": 0,
  8. "failed": 0
  9. },
  10. "hits": {
  11. "total": {
  12. "value": 2,
  13. "relation": "eq"
  14. },
  15. "max_score": 1,
  16. "hits": [
  17. {
  18. "_index": "students",
  19. "_id": "1",
  20. "_score": 1,
  21. "_source": {
  22. "name": "Jane Doe",
  23. "student_id": "111"
  24. }
  25. },
  26. {
  27. "_index": "students",
  28. "_id": "3",
  29. "_score": 1,
  30. "_source": {
  31. "name": "John Doe",
  32. "student_id": "333"
  33. }
  34. }
  35. ]
  36. }
  37. }

Parameters

The following table lists the terms lookup parameters.

ParameterData typeDescription
indexStringThe name of the index in which to fetch field values. Required.
idStringThe document ID of the document from which to fetch field values. Required.
pathStringThe name of the field from which to fetch field values. Specify nested fields using dot path notation. Required.
routingStringCustom routing value of the document from which to fetch field values. Optional. Required if a custom routing value was provided when the document was indexed.