Two different questions Elasticsearch can ask about the exact same clause.

The simple definitions

When a clause is evaluated in query context, Elasticsearch asks: “how well does this document match, and how relevant is it?” — producing a relevance score for every matching document. When the exact same kind of clause is evaluated in filter context instead, Elasticsearch asks a much simpler question: “does this document match, yes or no?” — with no scoring involved at all, just a clean inclusion or exclusion.

A side-by-side comparison to anchor everything that follows.

Understanding what “relevance scoring” actually means in practice.

Query context is what powers the classic search-engine experience — typing a phrase into a search box and getting back results ranked from most to least relevant. When a clause runs in query context, Elasticsearch doesn’t just decide whether a document matches; it calculates a numeric relevance score based on factors like how many of your search words appear, how rare those words are across the whole dataset, and how closely they appear together.

A plain, binary check with no notion of “how well” something matches.

Filter context strips relevance out of the equation entirely. A condition like “is the document’s status equal to published” or “is the price between 100 and 500” doesn’t have any meaningful notion of being “more” or “less” true — a document either satisfies the condition or it doesn’t. Filter context takes advantage of this by skipping the relevance calculation altogether, simply narrowing down which documents are considered at all.

Skipping relevance scoring isn’t the only performance benefit — caching plays a huge role too.

Because a filter’s result doesn’t depend on how a search query is phrased — a document either has status “published” or it doesn’t, regardless of what someone typed into a search box — Elasticsearch can safely remember, or cache, the result of frequently used filters. The next time the same filter condition is used, even as part of a completely different search, Elasticsearch can often reuse that cached result instead of recalculating it from scratch.

graph TD
    A[Search Request Arrives] --> B{Clause Type?}
    B -- Query Context --> C[Calculate relevance score]
    C --> D[Cannot reuse cached score across different searches]
    B -- Filter Context --> E[Check cache for this exact condition]
    E -- Cache Hit --> F[Reuse cached result instantly]
    E -- Cache Miss --> G[Evaluate condition, then cache it]
        

Real searches almost always use a thoughtful mix of both contexts together.

A typical, well-built search combines both worlds: a query-context clause handles the free-text part that genuinely benefits from relevance ranking, while one or more filter-context clauses narrow the results down to only the documents that meet exact, non-negotiable conditions. This gives you the best of both — ranked, relevant results, restricted to only the documents that are actually eligible to appear at all.

One clear question to ask yourself for every condition in a search.

Neither context is universally “better” — each is the right tool for a different job.

Choosing the right context can also play a quiet but real role in enforcing access rules correctly.

A few signals that reveal whether your searches are using each context effectively.

Common mistakes, and the patterns that fix them, drawn from real search designs.

Simple habits that keep search results both accurate and fast.

This distinction quietly shapes the search experience of many familiar applications.

A single search can certainly include multiple conditions, some in query context and some in filter context, but a single condition clause is evaluated in one context or the other, not both simultaneously.

No — filter context only decides whether a document is included or excluded. Any ordering you see in results comes entirely from query-context relevance scoring, or from an explicit sort you’ve requested separately.

Generally yes, especially for frequently reused conditions that benefit from caching, though the exact performance difference depends on the specific condition and how often it repeats across searches.

It will still correctly include or exclude documents based on whether they match, but you’ll lose any relevance-based ranking for that particular condition, since filter context never produces a score.

It’s worth learning early, since it directly affects both the quality of your search ranking and the performance of your cluster — but it becomes second nature quickly once you get used to asking “does relevance even apply here?”

Query context and filter context represent two fundamentally different questions Elasticsearch can ask about the same condition: “how relevant is this?” versus “does this qualify, yes or no?” Query context powers ranked, relevance-driven search, while filter context handles exact, binary conditions quickly and efficiently, often benefiting from caching. Well-designed searches deliberately combine both — free-text relevance in query context, and firm business rules and access restrictions in filter context — to deliver results that are both meaningful and fast.