Before diving into its structure, let’s establish why Elasticsearch needs a dedicated way to combine multiple conditions at all.

The problem: real searches rarely involve just one condition

A simple search — “find documents where the title contains this word” — is easy to express on its own. But real-world searches are almost always more nuanced: “find products in this category, priced under a certain amount, that are currently in stock, and ideally match this search term too.” A bool query is Elasticsearch’s mechanism for combining several individual conditions like these into a single, coherent search request.

The four “clause types” a bool query supports

What makes a bool query especially powerful is that it doesn’t treat every condition the same way. Instead, it organizes conditions into four distinct categories, each with a different meaning:

Understanding how these four clause types fit together as a whole reveals why bool queries are so flexible.

A bool query as a container of containers

Think of a bool query as an outer wrapper that holds up to four labeled sections — must, filter, should, and must_not — and each of those sections can hold one or more individual search conditions. None of the four sections are required to be present; you use exactly the ones that fit the search you’re trying to express, and nothing more.

flowchart TD
    A["bool query"] --> B["must: required, affects score"]
    A --> C["filter: required, no score impact"]
    A --> D["should: optional, boosts score"]
    A --> E["must_not: excluded entirely"]
    B --> B1["e.g. text must mention 'wireless headphones'"]
    C --> C1["e.g. category = Electronics"]
    D --> D1["e.g. brand = a preferred brand"]
    E --> E1["e.g. exclude out-of-stock items"]
        

Nesting: bool queries inside bool queries

Because a bool query is itself just another type of query, it can be placed inside another bool query’s clauses — allowing genuinely sophisticated logic, like “match condition A, and also match either condition B or condition C.” This nesting is what lets bool queries express logic as rich as combining AND, OR, and NOT concepts together, arbitrarily deep.

Understanding what happens internally when a bool query runs helps explain both its correctness and its performance characteristics.

Two categories of clause: scoring versus filtering

Internally, Elasticsearch treats must and should clauses very differently from filter and must_not clauses. Must and should clauses are evaluated as part of the actual relevance scoring process — meaning Elasticsearch calculates how well each document matches and factors that into an overall score. Filter and must_not clauses, by contrast, are evaluated as simple, binary yes/no checks that don’t participate in scoring at all — a document either passes them or it doesn’t.

How the four clause types combine logically

A document only appears in the results if it satisfies every must clause, every filter clause, and none of the must_not clauses. The should clauses don’t determine whether a document appears at all (unless there are no must or filter clauses present, in which case at least one should clause typically needs to match) — instead, they influence how highly a qualifying document is ranked relative to others.

Relevance scoring in must and should clauses

When a document satisfies a must or should clause, Elasticsearch calculates a relevance score contribution based on factors like how often the search term appears, how rare that term is across the whole index, and how long the field’s content is. These individual contributions are combined together into the document’s overall relevance score, which is what determines the order results are returned in.

Let’s trace what happens to a bool query from the moment it’s submitted to the moment ranked results come back.

Distribution across shards

Just like any other search, a bool query is sent by the coordinating node to every relevant shard, where each shard independently evaluates the query against its own slice of the data — applying the must, filter, should, and must_not logic locally, and calculating relevance scores for its own matching documents.

sequenceDiagram
    participant Client
    participant Coord as Coordinating Node
    participant Shard1 as Shard A
    participant Shard2 as Shard B
    Client->>Coord: Submit bool query
    Coord->>Shard1: Evaluate bool logic locally
    Coord->>Shard2: Evaluate bool logic locally
    Shard1-->>Coord: Local matches + scores
    Shard2-->>Coord: Local matches + scores
    Coord->>Coord: Merge and re-rank results
    Coord-->>Client: Final ranked results
        

Merging and final ranking

Once every relevant shard has reported back its own locally matching documents and their scores, the coordinating node merges all of these partial result sets together, sorts them by relevance score (or by another sort order if one was specified), and returns the final, unified list to the client.

Caching filter results for reuse

Because filter clauses are simple yes/no checks unaffected by scoring, Elasticsearch is often able to cache the results of frequently-used filter conditions, so that the same filter check doesn’t need to be fully recalculated every single time an identical or similar query runs — a performance benefit unique to filter-style clauses.

Bool queries are extremely flexible, but that flexibility comes with a learning curve and a few considerations worth knowing.

Because bool queries are often built dynamically from user input, they deserve some careful handling from a security standpoint.

Using filter clauses to enforce access boundaries

A very common and effective security pattern is to use a must_not or filter clause, added by the application itself rather than the end user, to enforce data-access boundaries — for example, always filtering results down to only the documents a particular user or tenant is permitted to see, regardless of what other conditions the user’s own search terms specify.

Risks of building queries from unvalidated user input

If parts of a bool query — such as field names, values, or the overall query structure — are constructed directly from untrusted user input without validation, there’s a risk of unexpected or overly broad queries being formed, which can degrade performance or unintentionally expose data that should have been filtered out. Validating and constraining what fields and values user input is allowed to influence is an important safeguard.

As bool queries grow more complex, keeping an eye on how they perform in production becomes increasingly valuable.

Watching for slow queries

Elasticsearch can log queries that take longer than a configured threshold to complete. Reviewing these slow-query logs often reveals bool queries with unnecessarily complex nesting, must clauses that should have been filters, or should clauses matching an excessive number of documents.

Understanding a query’s execution through explain and profiling tools

Elasticsearch provides tools that reveal exactly how a specific query was scored and executed, clause by clause. Using these tools on a bool query that isn’t returning the expected results, or that’s running slower than expected, can pinpoint precisely which clause is responsible for the behavior.

For applications that construct bool queries dynamically based on varying user input, logging a representative sample of the actual generated queries (not just the user’s raw search term) makes it far easier to diagnose unexpected performance or relevance issues later.

A few well-established habits consistently lead to bool queries that are both fast and easy to maintain.

These habits consistently separate bool queries that perform well from ones that quietly become a maintenance and performance headache.

Bool queries are the backbone of nearly every non-trivial search feature built on top of Elasticsearch.

Both require a document to match to appear in results, but must clauses contribute to the relevance score, while filter clauses are simple yes/no checks that don’t affect scoring at all — and are often faster and cacheable as a result.

No. You only include the clause types that are actually relevant to your search — many bool queries use just one or two of the four, such as a single must clause paired with a single filter clause.

By default, when a bool query has no must or filter clauses, at least one should clause typically needs to match for a document to be included in the results at all.

Yes, and this is a common and supported pattern for expressing more complex logic, such as combining an outer “AND” relationship with an inner “OR” relationship.

Must_not actively excludes any document matching its condition, while simply omitting a should clause has no exclusionary effect at all — it just means that particular optional boost isn’t being considered. They serve very different purposes.

It depends on the clauses involved. A bool query built thoughtfully — using filter clauses where appropriate — can be just as fast as, or even faster than, a poorly structured simple query, since filters can be cached and reused efficiently.

A bool query is the tool that lets Elasticsearch reflect the layered, nuanced way people actually think about their search requirements — separating what’s absolutely required, what’s simply preferred, and what should be excluded outright, all within a single structured request. By understanding the distinct roles of must, filter, should, and must_not clauses, and by deliberately choosing filter over must whenever relevance scoring isn’t needed, you can build searches that are both accurate and efficient. As your search logic grows more sophisticated, nesting bool queries inside one another lets that same clear structure scale to handle genuinely complex requirements without losing precision.