Catalog My learning Blog
Elasticsearch Tutorial: How Full-Text Search Works · Phase 3 · Lesson 17 · 3 min read

Elasticsearch Nested vs Parent-Child Documents

On this page
  1. Why arrays of objects match the wrong documents
  2. Nested fields keep objects together
  3. The cost of nested fields
  4. Parent-child relationships with join fields
  5. Usually the better choice: denormalize
  6. Check yourself

Why arrays of objects match the wrong documents

A product has two reviews: Ana gave 1 star, Bo gave 5. The question: did Ana give 5 stars? With a plain object mapping:

HTTP
PUT /reviews_object/_doc/1
{ "product": "Wireless Mouse", "reviews": [ { "user": "ana", "stars": 1 }, { "user": "bo", "stars": 5 } ] }
HTTP
GET /reviews_object/_search
{ "query": { "bool": { "must": [
    { "term": { "reviews.user": "ana" } },
    { "term": { "reviews.stars": 5 } } ] } } }
Code
total 1
  1    1.362   Wireless Mouse

It matches, wrongly. Internally, the array of objects is flattened into parallel arrays: reviews.user: [ana, bo] and reviews.stars: [1, 5]. The link between Ana and her rating is gone, so "ana" and "5" both appear somewhere.

Nested fields keep objects together

Map reviews as nested, and query it with a nested query:

Code
"reviews": { "type": "nested", "properties": { "user": { "type": "keyword" }, "stars": { "type": "byte" } } }
HTTP
GET /reviews_nested/_search
{ "query": { "nested": { "path": "reviews", "query": { "bool": { "must": [
    { "term": { "reviews.user": "ana" } },
    { "term": { "reviews.stars": 5 } } ] } } } } }
Code
total 0

Correct. Asking for Ana's 1-star review instead matches, and inner_hits returns exactly which object matched:

Code
inner hit: [{'user': 'ana', 'stars': 1}]
Object arrays are flattened into independent value lists, losing which values belong together; nested fields store each object as its own hidden document so conditions apply within one object.
Object arrays are flattened into independent value lists, losing which values belong together; nested fields store each object as its own hidden document so conditions apply within one object.

The cost of nested fields

Each nested object is stored as a hidden Lucene document next to its parent. The lab's indices show it:

Code
index          docs.count
reviews_nested          3     <- 1 product + 2 nested reviews
reviews_object          1

The course's products index (12 products, 2 reviews each) reported 36 documents. Consequences:

  • Updating one review reindexes the parent and all its nested objects.
  • Thousands of nested objects per document get slow; the default limit is 10,000 per document (index.mapping.nested_objects.limit).
  • Nested queries and nested aggregations are slower than flat ones.

Parent-child relationships with join fields

For children that change often or are very numerous (questions and their answers, a company and its millions of employees), a join field stores parents and children as separate documents in the same index and shard:

Code
"relation": { "type": "join", "relations": { "question": "answer" } }

Children are indexed and updated independently, with routing set to the parent's ID so they land on the same shard. Queries use has_child and has_parent, which are much slower than nested queries. Use join only when update patterns require it.

Usually the better choice: denormalize

Search engines work best with flat, self-contained documents. Often the right answer is neither nested nor join, but copying the data you search on into each document (Day 18):

ApproachUse when
Plain object arrayFields are searched independently; cross-matching doesn't matter
nestedConditions must apply within one object; objects per document are modest; updates are rare
joinChildren are many or updated independently and often
DenormalizeYou can copy the needed fields into each searched document

Check yourself

Arrays of objects are flattened into separate value lists per field, so the link between which reviewer gave which rating is lost. Values from different objects can then satisfy the same query. Nested mapping keeps each object together.

Each nested object is stored as a hidden Lucene document alongside its parent, so a product with two reviews is three Lucene documents. That's why many nested objects increase index size and update cost.

When child documents are numerous or updated independently and often, so reindexing the whole parent on every change is too costly.

Nested objects are stored as hidden documents in the same block as their parent, so changing one review reindexes the whole parent and every nested document with it. Frequently updated children are a sign to use a join field or separate index.

index.mapping.nested_objects.limit, 10,000 by default, caps nested objects per document, and index.mapping.nested_fields.limit caps nested fields per index. They stop one document from creating millions of hidden documents.