Elasticsearch Nested vs Parent-Child Documents
On this page
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:
PUT /reviews_object/_doc/1
{ "product": "Wireless Mouse", "reviews": [ { "user": "ana", "stars": 1 }, { "user": "bo", "stars": 5 } ] }GET /reviews_object/_search
{ "query": { "bool": { "must": [
{ "term": { "reviews.user": "ana" } },
{ "term": { "reviews.stars": 5 } } ] } } }total 1
1 1.362 Wireless MouseIt 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:
"reviews": { "type": "nested", "properties": { "user": { "type": "keyword" }, "stars": { "type": "byte" } } }GET /reviews_nested/_search
{ "query": { "nested": { "path": "reviews", "query": { "bool": { "must": [
{ "term": { "reviews.user": "ana" } },
{ "term": { "reviews.stars": 5 } } ] } } } } }total 0Correct. Asking for Ana's 1-star review instead matches, and inner_hits returns exactly which object matched:
inner hit: [{'user': 'ana', 'stars': 1}]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:
index docs.count
reviews_nested 3 <- 1 product + 2 nested reviews
reviews_object 1The 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
nestedaggregations 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:
"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):
| Approach | Use when |
|---|---|
| Plain object array | Fields are searched independently; cross-matching doesn't matter |
nested | Conditions must apply within one object; objects per document are modest; updates are rare |
join | Children are many or updated independently and often |
| Denormalize | You 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.