When would you use terms_lookup instead of inlining values in a terms query?

## What the terms query does `{"terms": {"status": ["open", "pending"]}}` matches documents whose `status` field contains at least one of the listed values. It is term-level, so **none of the values are analyzed** — they are looked up byte for byte in the term dictionary. Everything that makes a `term` query fail on a `text` field applies here identically, only multiplied by the length of the list. `terms` is effectively a `bool` of `should` clauses collapsed into one efficient clause, and it does not compute per-term relevance: all matches get the same constant score, which makes it a natural filter-context clause. The inline list is bounded by the index setting `index.max_terms_count`, which defaults to 65,536. Exceeding it fails the request rather than degrading quietly — a useful guardrail, because a request carrying tens of thousands of literal values is expensive to parse and to execute regardless. ## The terms lookup form Instead of an array, the field takes an object: ```json { "terms": { "author_id": { "index": "user_follows", "id": "u-42", "path": "following" } } } ``` Elasticsearch performs an internal get of document `u-42` from `user_follows`, reads the array at `following` from its `_source`, and uses those values as the terms. An optional `routing` parameter tells it which shard to fetch from when the lookup index uses custom routing. Two details matter. First, the values come from `_source`, so the lookup field does not need to be indexed — but `_source` must be enabled on that index. Second, the path may point into nested objects with dotted notation, and the value there must be an array (or a single value) of the terms you want. ## When it is the right call The test is: *does this list already exist as data, and is it big or hot enough that shipping it on every request is wasteful?* Good fits are permission and personalization lists — the categories a tenant may see, the authors a user follows, the product ids in a saved basket, a blocklist. These change independently of the search, they can be large, and they are already stored per user. Keeping them server-side means the application layer does not need to read them before every search, request bodies stay small, and the list has exactly one writer. Poor fits are small, request-specific lists — three status values, a handful of ids the caller already has in hand. There, `terms_lookup` buys nothing and costs an extra fetch. ## The operational costs Every search that uses the lookup does an internal get first. That get is cheap but it is not free, and it lands on whichever shard holds the lookup document. If a thousand searches a second all read the same lookup document, that shard becomes a hotspot. The conventional mitigation is to make the lookup index tiny and ubiquitous: one primary shard, and `auto_expand_replicas` set so a copy lives on every data node. Then the get is always node-local and no single shard carries the whole read load. The second cost is freshness semantics. The document is read at search time, so updates to the list take effect as soon as they are visible to search — which is bounded by the refresh interval, not by any cache you control. That is usually what you want for permissions, but it means an update to the lookup document is not instantly reflected in searches issued in the same second unless you refresh. The third is size. A lookup that resolves to an enormous array is just as expensive to execute as the same array inlined; moving it server-side removes the transfer cost, not the matching cost. ## Alternatives worth naming When the list is genuinely huge and stable, denormalizing is often better: write the group membership onto the searchable documents themselves and filter on a single term. That trades index-time work and reindexing on membership change for a much cheaper query. When the list is derived from another index by a join-like relationship, the honest answer in Elasticsearch is usually denormalization rather than any lookup mechanism, because there is no server-side join. ## Related term-level lookup A close cousin is the `ids` query — `{"ids": {"values": ["1", "2", "3"]}}` — which matches on the `_id` metadata field directly. It is the right tool when you have document ids in hand and want them in one search request alongside other clauses; if you want the documents and nothing else, the multi-get API is a cheaper path than a search.