A term query finds documents that contain an exact value in a specified field. Not “similar to,” not “contains the word somewhere within it” — exact, byte-for-byte match. It’s the simplest possible query Elasticsearch offers: you give it a field name and a value, and it returns every document where that field holds precisely that value.

What it is: a query clause that matches documents where a field’s stored value is exactly equal to the value you provide, with no text processing applied to your input.

Why it exists: many real-world lookups genuinely need exact matching — a status code, a category ID, a country code — where “close enough” isn’t good enough and full-text relevance scoring would actively get in the way.

Where it’s used: filters in e-commerce facets, exact status/category lookups, matching structured identifiers, and as a building block inside more complex boolean queries.

The Classic Beginner Trap

Here’s exactly why “New York” so often fails to match. If “city” is mapped as a “text” field, Elasticsearch’s analyzer breaks “New York” into two separate tokens at index time: “new” and “york” (both lowercased). A term query searching for the exact string “New York” is looking for that precise, unbroken, capitalized phrase in the index — but that phrase was never stored as a single token; only “new” and “york” were. The term query for “New York” fails, while a term query for “new” would succeed, since that’s literally what got indexed.

Elasticsearch’s query language broadly splits into two families: full-text queries (like “match,” which analyze your input the same way the field was analyzed) and term-level queries (like “term,” “terms,” and “range,” which operate on exact, unanalyzed values). The term query is the flagship member of the term-level family.

graph TD
    A["term query: field='status', value='SHIPPED'"] --> B{Field mapped as
keyword?}
    B -- Yes --> C[Compare 'SHIPPED' exactly
against stored values]
    B -- No, mapped as text --> D[Compare against individual
lowercased tokens - likely mismatch]
    C --> E[Matching documents returned]
    D --> F[Few or no matches - classic beginner trap]
        

A related but distinct query, “terms,” extends this same exact-match behavior to a whole list of values at once — for example, matching any document where “status” equals “shipped,” “delivered,” or “returned” — internally running the same kind of dictionary lookup, just for multiple values in a single pass.

The trade-off is precision versus flexibility. A term query gives you rigid, exact, and very fast matching — perfect when your data genuinely has discrete exact values, but the wrong tool the moment you actually need to search natural language.

Term queries are simple, but they still leave useful operational signals worth watching, especially at scale:

• High zero-hit rate: a sudden spike in term queries returning zero results often signals a mapping mismatch (querying a text field) or a data formatting change upstream (like inconsistent casing).
• Filter cache effectiveness: since term queries used in filter context are cacheable, monitoring cache hit rates helps confirm the cluster is actually benefiting from that caching, rather than repeatedly recomputing identical filters.
• Slow query logs: although term queries are normally fast, an unusually slow one can indicate an oversized “terms” list or a field with an excessive number of unique values.