Before defining the query, we need one quick reminder about the data type it is built to search.

A nested query is a special query clause in Elasticsearch used to search fields that have been mapped with the nested data type. Recall that a nested field takes an array of objects and, instead of flattening every object’s properties into shared arrays, stores each object as its own small, hidden document living right alongside its parent. A nested query is the only query clause that knows how to reach into those hidden documents and search them correctly, one at a time, without ever mixing values from two different array entries.

The defining feature of a nested query is that every condition placed inside it must be satisfied by one single hidden child document — not scattered across several. This single rule is what makes nested queries fundamentally different from, and more precise than, an ordinary compound query built from must or filter clauses pointed at the same fields.

It helps to think of a nested query as a kind of scoped sub-search that happens entirely within the boundaries of one nested field’s hidden documents, before its result is ever handed back up to the parent-level search. From the outside, a nested query behaves like any other query clause — it produces a match or no match, and optionally a relevance score — but internally, it is running its own miniature search restricted to a specific group of hidden documents, one parent at a time.

Understanding the failure mode a nested query prevents is the fastest way to understand why it exists at all.

Suppose a product document contains a nested reviews field, with entries for several different reviewers and their ratings. If you write an ordinary compound query asking for “author is Alice” and, separately, “rating is 1,” pointed directly at the review sub-fields without wrapping them in a nested query, Elasticsearch will search each condition independently across all hidden review documents under that product and simply confirm that both conditions were true somewhere among them — not necessarily in the same review.

This failure is especially dangerous because it does not throw an error or produce an empty result — it produces a result that looks completely normal. The search returns a document, a user clicks into it expecting to see Alice’s harsh review, and instead finds a five-star review from Alice sitting next to a scathing one-star review from someone else entirely. Nothing in the interface signals that anything went wrong; the mismatch is silent by nature.

The nested query clause is Elasticsearch’s answer to this exact gap. It does not change how the data is stored — that decision was already made back when the field was mapped as nested — but it changes how the search engine is instructed to interpret conditions aimed at that field, restoring the “same object” guarantee that a plain compound query cannot provide.

It is also worth noting that this failure mode is not unique to text-matching conditions — it applies equally to numeric ranges, date comparisons, and exact-value filters. A range condition asking for “quantity above 10” combined separately with “price below 50,” aimed at a nested line-items field without a nested query wrapper, faces the exact same risk: the two numeric facts can be pulled from two completely different line items on the same order, producing a match that has no basis in any single real line item.

A nested query is built from a small, fixed set of parts, each with a distinct job.

Score Mode in Plain Language

When more than one hidden child document under a path matches the inner query, Elasticsearch needs a rule for turning several relevance scores into one overall contribution to the parent document’s score. The available modes let you choose the highest matching score among all matching children, the lowest, the average across all of them, the sum of all of them, or to ignore scoring altogether and treat the nested query purely as a yes-or-no filter.

Because the inner query section accepts any ordinary query clause, it can itself be a compound query built from multiple conditions — a bool query with several must and should clauses, for instance — as long as every one of those inner conditions is still being evaluated against fields belonging to the same nested object. This is what makes a nested query flexible enough to express fairly rich per-entry conditions, such as “author is Alice, rating is below 3, and the review text mentions a specific keyword,” while still preserving the same-object guarantee for all three conditions at once.

To understand how a nested query runs efficiently, we need to revisit how nested data is physically stored.

Recall that nested fields store each array entry as its own small Lucene document, kept physically adjacent to its parent document within the same segment. A nested query is built specifically to take advantage of this adjacency: rather than scanning the whole index for candidate parents and then separately checking children, it works the other way around, first finding matching hidden child documents and then walking directly to the parent that sits right next to them in the block.

graph TD
    P[Parent Document: Product 42] --> C1[Child: review by Alice, rating 1]
    P --> C2[Child: review by Bob, rating 5]
    P --> C3[Child: review by Carol, rating 4]
    Q[Nested Query: author=Alice AND rating=1] -.searches.-> C1
    C1 -.adjacent, walk to.-> P
    P --> R[Returned as a match]
        

This design is what allows nested queries to avoid the kind of expensive, index-wide join that a naive implementation would otherwise require. Because Lucene guarantees the block ordering described earlier — child documents always sit immediately before their parent — the query engine can locate a parent from a matching child using a simple, fast internal lookup rather than a broader scan across unrelated parts of the index.

The same architecture also explains a limitation worth remembering early: a nested query can only search within one nested path at a time. If a document has two separate nested fields — say, reviews and images — a single nested query cannot combine conditions from both into one inner match; each nested path requires its own separate nested query clause, later combined at the parent level using an ordinary bool query.

This architectural choice is not an arbitrary restriction; it follows directly from how hidden child documents are tagged and grouped. Each hidden child document carries metadata identifying exactly one nested path, so there is no single hidden document that could ever represent “an entry from reviews and an entry from images at once” — the two groups of hidden documents are entirely separate populations sitting in the same physical neighborhood as their shared parent, but never merged with each other.

graph TD
    P[Parent: Product 42] --> R1[Review child 1]
    P --> R2[Review child 2]
    P --> I1[Image child 1]
    P --> I2[Image child 2]
    NQ1[Nested Query path=reviews] -.scopes only.-> R1
    NQ1 -.scopes only.-> R2
    NQ2[Nested Query path=images] -.scopes only.-> I1
    NQ2 -.scopes only.-> I2
        

Here is what actually happens, in order, when Elasticsearch receives a nested query.

sequenceDiagram
    participant Client
    participant ES as Query Engine
    participant Lucene as Lucene Segment
    Client->>ES: Nested query on path "reviews"
    ES->>Lucene: Restrict scope to reviews children
    Lucene-->>ES: Candidate child documents
    ES->>ES: Evaluate inner query per child
    ES->>Lucene: Resolve matching children to parents
    ES->>ES: Combine scores using score_mode
    ES-->>Client: Parent documents (with inner hits if requested)
        

It is worth dwelling briefly on step four, parent resolution, since it is the step that most clearly distinguishes a nested query’s execution from a naive join. Rather than performing a lookup against an index or a separate data structure to find “which parent owns this child,” the query engine relies purely on the fixed physical ordering established at indexing time: because every block of hidden children is guaranteed to sit immediately before its parent within the same segment, walking to the parent from a matching child is a short, local step rather than a search of its own.

This also explains why nested queries remain efficient even as an index grows very large in terms of total document count: the cost of resolving a matching child to its parent does not grow with the size of the whole index, only with the local structure of that one parent’s block, which stays constant regardless of how many other parents and their own nested children exist elsewhere in the index.

Nested queries rarely live alone; they are usually one clause among several in a larger search request.

A nested query behaves like any other query clause once it produces its yes-or-no match and its score: it can be placed inside a bool query’s must, filter, should, or must_not sections, sitting alongside ordinary conditions on the parent document’s own fields. This is what allows a single search request to combine “category is Electronics” (a parent-level condition) with “at least one review has author Alice and rating 1” (a nested condition) into one coherent query.

flowchart LR
    B[Bool Query] --> M1[must: category = Electronics]
    B --> M2[must: nested query on reviews]
    M2 --> I1[author = Alice]
    M2 --> I2[rating = 1]
    B --> F[Final match: parent satisfies both top-level and nested conditions]
        

When two separate nested fields need to be searched in the same request — for example, requiring both a matching review and a matching image tag — each nested path gets its own nested query clause, and the two clauses are then joined together using an ordinary bool query at the parent level, since a single nested query can never reach across two different paths at once.

Multi-level nesting follows the same joining principle one level deeper: when a nested field itself contains another nested field, the inner nested query is placed inside the outer nested query’s own inner query section, with its own separate path pointing to the deeper level, so that conditions can be scoped precisely at whichever level of the hierarchy they belong to.

A practical example makes this concrete: imagine an order document with a nested line_items field, and each line item itself has a nested discounts field listing multiple discount codes applied to that specific item. A search for “a line item where a specific discount code was applied and the resulting price is below a threshold” requires an outer nested query scoped to line_items, containing an inner nested query scoped to line_items.discounts, with the price condition sitting in the outer query and the discount-code condition sitting in the inner one — each condition anchored precisely to the level of the hierarchy where it actually belongs.

A nested query alone tells you a parent matched; inner hits tell you which specific entry is responsible.

Without inner hits, a nested query’s result looks identical to any other query’s result: a list of matching parent documents, each returned in full, with no indication of which review, line item, or skill entry actually satisfied the inner condition. For many applications this is not enough — a review platform, for instance, usually wants to display the specific matching review to the user, not force them to scan the whole list themselves.

When inner hits are requested alongside a nested query, Elasticsearch attaches a separate section to each matching parent document in the response, containing the specific nested object or objects that satisfied the inner query, along with their own individual relevance scores. This lets an application highlight precisely which review, line item, or skill entry drove the match, rather than presenting the whole parent and leaving the user to guess.

Inner hits also carry their own independent highlighting and sorting configuration, separate from the outer query’s settings, which means an application can, for example, sort the outer results by overall relevance while still sorting the inner hits within each result by rating or date, tailoring the presentation of nested entries to whatever makes sense for the specific feature being built.

These two features share a name and a mental model, but they answer very different questions.

A nested query answers a yes-or-no question about parent documents: “does this parent have at least one nested entry matching these conditions?” A nested aggregation, by contrast, answers a statistical question scoped to the nested entries themselves: “across all nested entries under this path, what is the average, count, minimum, or maximum of a given field?” The two can be used independently or combined in the same request, but they are solving fundamentally different problems.

The two frequently appear together in a single search request: a nested query narrows down which parent documents are relevant in the first place, while a nested aggregation, computed independently within the same request, reports statistics about the nested entries across the matching set — for example, finding products with at least one critical review, while also reporting the overall average rating across every review on those same products.

A nested query buys correctness, but that correctness is not free at query time.

It is useful to frame this trade-off the same way as the underlying nested data type itself: a nested query trades a modest, predictable amount of extra computation for a guarantee that would otherwise be impossible to obtain from a flattened representation of the same data. Teams that understand this trade-off tend to reach for nested queries confidently exactly where the correctness guarantee matters, while staying alert to array size as the main lever affecting how expensive that guarantee becomes in practice.

A handful of recurring shapes cover most real nested-query use cases — and a handful of anti-patterns cover most of the mistakes.

Small habits around how nested queries are written and combined make a large difference in both correctness and performance.

Nested queries are efficient by design, but that efficiency depends on assumptions worth monitoring over time.

The performance of a nested query is closely tied to how many hidden child documents exist under the target path per parent document, since the inner condition must be evaluated against each candidate before any parent resolution can happen. A dataset that starts with a handful of entries per parent and later grows into the hundreds or thousands can see nested query latency rise correspondingly, even if the query itself never changes.

It is also worth distinguishing between latency caused by the nested query itself and latency caused by other clauses running alongside it in the same bool query. Isolating a nested query by running it on its own, without the surrounding conditions, is a quick way to confirm whether it is genuinely the bottleneck before spending time optimizing the wrong part of a search request.

Nested queries interact with a few existing security concerns in ways worth calling out explicitly.

Because inner hits can expose specific nested objects that a user might not otherwise be authorized to see individually, applications that combine nested queries with field-level or document-level security should verify that inner hits results are filtered through the same access rules as the rest of the response, rather than assuming that document-level authorization alone is sufficient.

A related consideration applies to logging and auditing: because nested queries can express fairly specific conditions about individual array entries, query logs that capture full request bodies may end up recording sensitive details — such as a specific reviewer’s name paired with a specific rating, or a specific employee’s exact skill level — that would otherwise only be visible through normal search results. Teams operating in regulated environments should treat nested query logs with the same care as the underlying data they describe.

Seeing nested queries at work across different domains makes their value concrete.

Across each of these examples, the nested query is doing the same job: enforcing that several conditions describe one real entity within an array, not an accidental combination stitched together from unrelated entries. That single guarantee is the entire reason the clause exists, however different the surrounding application might look.

What varies across these examples is not the underlying mechanism but the stakes attached to getting it wrong. A miscombined product review is a minor annoyance to a shopper; a miscombined line item in an order system can mean shipping the wrong quantity of the wrong product; a miscombined skill match in recruiting can mean overlooking or wrongly surfacing a candidate. The nested query’s correctness guarantee matters more, not less, as the real-world consequences of a wrong match grow more serious — which is exactly why it is worth taking seriously even in domains that seem, at first glance, low-stakes.

A short set of questions that come up repeatedly once teams start writing nested queries in real projects.

No, a nested query requires the target path to be mapped as the nested data type; running it against a plain object field either returns an error or, with ignore-unmapped enabled, silently matches nothing.

No, a single nested query is always scoped to one path; searching across two nested fields requires two separate nested query clauses combined together with an ordinary bool query.

Only if a score mode other than none is used; setting score mode to none turns the nested query into a pure true-or-false filter that does not contribute to relevance scoring.

No, inner hits is entirely optional; a nested query works perfectly well on its own to filter or score parent documents, with inner hits added only when the specific matching entry needs to be returned.

The inner nested query is placed inside the outer nested query’s own inner query, with its own separate path describing the deeper level, so each level of the hierarchy is scoped by its own nested query.

The most common causes are an incorrect path string that does not exactly match the mapped nested field name, or a field that was mapped as a plain object rather than nested, both of which prevent the nested query from finding any hidden child documents to search.

Yes, when used in filter context with score mode none, nested queries can benefit from Elasticsearch’s filter caching just like other non-scoring queries, improving performance for frequently repeated searches.

Yes, the inner query section of a nested query accepts any ordinary query type, including full-text match queries, so a nested query can search for specific words inside a nested text field while still requiring other conditions to hold on the same entry.

No, a nested query considers all hidden child documents under a path regardless of their original array position, since matching is based purely on which entries satisfy the inner condition, not on where they appeared in the source array.

A nested query is the query clause built specifically to search fields mapped as the nested data type, guaranteeing that every condition inside it is checked against one single hidden child document rather than scattered across unrelated array entries. It is built from a path identifying which nested field to search, an inner query describing what must be true within one entry, a score mode controlling how multiple matches combine into relevance, and an optional inner hits block that reveals exactly which entry matched. Used correctly — one path per clause, combined through ordinary bool queries at the parent level, and paired with inner hits only when genuinely needed — the nested query restores the correctness that a plain compound query cannot guarantee against arrays of objects, at a query-time cost that scales with how large those arrays grow.

The broader lesson underlying this entire guide is that correctness in search systems is rarely automatic once data takes on any kind of internal structure. Whenever a document contains a list of things, and more than one property of those things matters to a query at once, it is worth stopping to ask whether an ordinary query can actually answer that question truthfully, or whether the nested query’s stricter, same-object guarantee is required. That single habit of pausing to ask the question is often the difference between a search feature that works and one that quietly, invisibly, gets some answers wrong.

As a final practical note, treat the nested query and the nested mapping decision as two halves of one design choice, not two independent steps. A field mapped as nested with no query ever taking advantage of its cross-field guarantees gains nothing from the extra storage cost, while a query attempting nested-style precision against a field that was never mapped as nested cannot succeed no matter how carefully it is written. Getting real value from this feature means making both decisions together, with the same specific query requirement in mind from the start.