terms-query.asciidoc 2.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114
  1. [[query-dsl-terms-query]]
  2. === Terms Query
  3. Filters documents that have fields that match any of the provided terms
  4. (*not analyzed*). For example:
  5. [source,js]
  6. --------------------------------------------------
  7. GET /_search
  8. {
  9. "query": {
  10. "terms" : { "user" : ["kimchy", "elasticsearch"]}
  11. }
  12. }
  13. --------------------------------------------------
  14. // CONSOLE
  15. [float]
  16. [[query-dsl-terms-lookup]]
  17. ===== Terms lookup mechanism
  18. When it's needed to specify a `terms` filter with a lot of terms it can
  19. be beneficial to fetch those term values from a document in an index. A
  20. concrete example would be to filter tweets tweeted by your followers.
  21. Potentially the amount of user ids specified in the terms filter can be
  22. a lot. In this scenario it makes sense to use the terms filter's terms
  23. lookup mechanism.
  24. The terms lookup mechanism supports the following options:
  25. [horizontal]
  26. `index`::
  27. The index to fetch the term values from. Defaults to the
  28. current index.
  29. `type`::
  30. The type to fetch the term values from.
  31. `id`::
  32. The id of the document to fetch the term values from.
  33. `path`::
  34. The field specified as path to fetch the actual values for the
  35. `terms` filter.
  36. `routing`::
  37. A custom routing value to be used when retrieving the
  38. external terms doc.
  39. The values for the `terms` filter will be fetched from a field in a
  40. document with the specified id in the specified type and index.
  41. Internally a get request is executed to fetch the values from the
  42. specified path. At the moment for this feature to work the `_source`
  43. needs to be stored.
  44. Also, consider using an index with a single shard and fully replicated
  45. across all nodes if the "reference" terms data is not large. The lookup
  46. terms filter will prefer to execute the get request on a local node if
  47. possible, reducing the need for networking.
  48. [float]
  49. ===== Terms lookup twitter example
  50. At first we index the information for user with id 2, specifically, its
  51. followers, than index a tweet from user with id 1. Finally we search on
  52. all the tweets that match the followers of user 2.
  53. [source,js]
  54. --------------------------------------------------
  55. PUT /users/user/2
  56. {
  57. "followers" : ["1", "3"]
  58. }
  59. PUT /tweets/tweet/1
  60. {
  61. "user" : "1"
  62. }
  63. GET /tweets/_search
  64. {
  65. "query" : {
  66. "terms" : {
  67. "user" : {
  68. "index" : "users",
  69. "type" : "user",
  70. "id" : "2",
  71. "path" : "followers"
  72. }
  73. }
  74. }
  75. }
  76. --------------------------------------------------
  77. // CONSOLE
  78. The structure of the external terms document can also include array of
  79. inner objects, for example:
  80. [source,js]
  81. --------------------------------------------------
  82. PUT /users/user/2
  83. {
  84. "followers" : [
  85. {
  86. "id" : "1"
  87. },
  88. {
  89. "id" : "2"
  90. }
  91. ]
  92. }
  93. --------------------------------------------------
  94. // CONSOLE
  95. In which case, the lookup path will be `followers.id`.