ElasticSearch父子文档：从数据建模到关联查询的工程实践

1. 为什么需要父子文档：从一次数据建模翻车说起

刚接触 ElasticSearch 那会儿，我踩过一个特别典型的坑。当时手上有个商品管理系统的搜索需求，一个商品有基础信息（标题、价格、类目），还有一堆变长的附属信息（多个 SKU、多条用户评价、多个规格参数）。我第一反应是全部塞进一个文档里，用 nested 类型搞定。结果数据量一上来，问题就炸了：每次改一条评价，整个商品文档都要重建索引，写入放大严重，而且 nested 查询在数据量大时性能衰减得厉害。

后来才认真去研究 ElasticSearch 提供的父子文档（Parent-Child / Join 类型）方案。它的核心价值在于：把原本属于同一个文档的不同实体拆成独立文档存储，但依然保持关联关系，并且支持跨文档的关联查询。这跟 nested 最大的区别是——nested 的子对象是"嵌"在父文档里的，父子文档的子文档是独立存储的，更新子文档不会导致父文档重建。

这个特性直接解决了几类场景的痛点：商品与 SKU、博客与评论、订单与订单明细、组织架构与员工。这些场景的共同特征是"一对多"或"多对多"，且子文档更新频繁、数量可能很大。如果你正在做这类数据建模，或者被 nested 的写入性能折磨过，那父子文档值得你花时间吃透。

需要提前说明的是，父子文档不是银弹。它有自己的代价：查询比 nested 慢、需要额外的内存维护 join 字段的全局序数（global ordinals）、一个索引只能有一个 join 字段。所以选型之前一定要想清楚你的读写比例和查询模式。下面我会从设计思路、核心原理、实操步骤到踩坑排查，完整地讲一遍。

2. 父子文档的核心设计思路与选型考量

2.1 父子文档到底解决了什么问题

要理解父子文档，先得理解 ElasticSearch 的一个基本事实：文档是 ElasticSearch 里最小的独立存储和更新单元。一个文档要么整体写入，要么整体更新，没有"只更新文档里某个字段"这种操作（update 本质也是重建整个文档）。这个特性决定了：如果一个父实体带着大量子实体塞在同一个文档里，任何子实体的变化都会触发整个文档的重建。

父子文档的思路是把"父"和"子"拆成两个独立文档，通过一个特殊的join字段建立关联。父文档和子文档在物理上是分开的，各自独立更新。查询的时候，ElasticSearch 通过 join 字段的映射关系，把父子关联起来做联合查询。

这里有个关键点很多人会误解：父子文档必须位于同一个索引的同一个分片内。ElasticSearch 通过路由（routing）保证这一点——子文档在写入时会自动继承父文档的 routing 值，从而落到同一个分片。这也是为什么父子文档的关联查询能高效执行，因为它不需要跨分片。

2.2 父子文档 vs nested：怎么选

这是选型时绕不开的对比。我把两者的核心差异整理成一张表，方便你对照自己的场景：

选型的经验法则很简单：子对象数量少、更新不频繁、查询以父带子为主，用 nested；子对象数量大、更新频繁、需要独立维护子文档，用父子文档。我见过不少团队一上来就用父子文档，结果查询复杂度陡增，其实他们的场景 nested 完全够用。反过来，也有团队硬用 nested 扛高频更新的评论数据，最后写入性能崩盘。

2.3 join 字段的设计哲学

父子文档的核心是join字段，它的定义方式很特别：

{ "mappings": { "properties": { "relation": { "type": "join", "relations": { "product": "sku" } } } } }

这里的relations定义了一个父子关系：product是父，sku是子。注意这个字段名我用了relation，你可以叫任何名字，但一个索引里只能有一个 join 字段。这个限制意味着：如果你有多个维度的父子关系（比如商品-SKU 和商品-评论），要么用同一个 join 字段定义多组关系，要么拆索引。

join 字段在底层维护了一个全局序数映射，把每个父文档和子文档的 ID 映射成一个整数。查询时通过这个映射快速定位关联文档。这个映射是懒加载的，第一次用到某个分片的 join 查询时才会构建，构建过程会消耗内存和 CPU。这就是为什么父子文档对内存敏感——如果你的父子关系特别复杂、文档特别多，global ordinals 的构建可能成为瓶颈。

提示：join 字段的 global ordinals 构建是分片级别的，且会在 refresh 后失效重建。如果你的写入非常频繁，join 查询的性能会明显波动。生产环境建议控制 refresh 频率，或者接受这个代价。

3. 父子文档的核心原理与关键细节

3.1 父子文档的写入与路由机制

理解路由机制是掌握父子文档的关键。ElasticSearch 默认用文档 ID 的哈希值来决定文档落到哪个分片。但子文档必须和父文档在同一个分片，否则 join 查询无法执行。所以写入子文档时，必须显式指定routing参数，值就是父文档的 ID。

# 写入父文档 PUT /shop/_doc/1 { "name": "某款无线耳机", "price": 299, "relation": { "name": "product" } } # 写入子文档，routing 必须是父文档 ID PUT /shop/_doc/sku-1?routing=1 { "sku_name": "黑色标准版", "stock": 100, "relation": { "name": "sku", "parent": "1" } }

如果你忘了指定 routing，子文档可能落到别的分片，那么父子关联就断了——查询时找不到父文档，或者报错。这是新手最容易犯的错误之一。我建议在应用层封装写入逻辑时，强制要求子文档写入必须带 routing，最好做成一个统一的工具方法，避免遗漏。

3.2 has_child 与 has_parent 查询

父子文档的查询主要靠两个查询子句：has_child和has_parent。

has_child是"从父查子"：找出所有满足子文档条件的父文档。比如"找出所有有库存大于 50 的 SKU 的商品"：

{ "query": { "has_child": { "type": "sku", "query": { "range": { "stock": { "gte": 50 } } }, "score_mode": "max" } } }

has_parent是"从子查父"：找出所有父文档满足条件的子文档。比如"找出所有属于价格大于 200 的商品的 SKU"：

{ "query": { "has_parent": { "parent_type": "product", "query": { "range": { "price": { "gt": 200 } } }, "score_mode": "score" } } }

这两个查询的score_mode参数很关键，它决定子文档/父文档的评分如何影响最终结果。可选值有none、score、max、min、avg、sum。默认是none，意味着不把关联文档的评分计入。如果你希望"库存越高的商品排名越靠前"，就得用max或sum。这个参数调不对，搜索结果的相关性排序会很奇怪。

3.3 父子文档的聚合与排序限制

父子文档在聚合和排序上有明显限制，这是选型时必须知道的。你不能直接对子文档字段做聚合然后按父文档分组，因为父子是独立文档，聚合是在文档级别进行的。要实现"按商品分组统计 SKU 平均价格"这种需求，得用children聚合配合parent聚合，写法复杂且性能一般。

排序方面，has_child查询返回的是父文档，你无法直接按子文档字段排序。如果业务强依赖"按子文档某字段排序父文档"，父子文档会很别扭，这时候 nested 反而更合适。

注意：父子文档的 join 查询在数据量大时，global ordinals 的构建可能占用大量堆内存。如果你的父子文档总量超过千万级，务必监控 JVM 堆使用，必要时调大堆或优化查询模式。

4. 完整实操：从零搭建一个商品-SKU 父子文档索引

4.1 索引创建与 mapping 设计

我以一个电商商品-SKU 场景为例，完整走一遍。先创建索引，定义 join 字段：

PUT /shop_parent_child { "settings": { "number_of_shards": 3, "number_of_replicas": 1, "refresh_interval": "5s" }, "mappings": { "properties": { "relation": { "type": "join", "relations": { "product": "sku" } }, "name": { "type": "text" }, "price": { "type": "double" }, "category": { "type": "keyword" }, "sku_name": { "type": "text" }, "stock": { "type": "integer" }, "sku_price": { "type": "double" } } } }

这里我把refresh_interval设成 5s，而不是默认的 1s。原因是父子文档的 join 查询依赖 global ordinals，频繁 refresh 会导致 ordinals 反复重建，影响查询性能。5s 是一个折中值，兼顾了数据可见性和性能。如果你的业务对实时性要求极高，可以保持 1s，但要接受性能波动。

分片数设成 3 是拍脑袋的吗？不是。分片数要根据数据量和节点数来定。假设你的商品有 100 万，每个商品平均 10 个 SKU，那就是 1100 万文档。单分片建议控制在 30-50GB 以内，按每个文档 1KB 估算，1100 万文档约 11GB，3 个分片每个约 3.7GB，很宽裕。分片不是越多越好，分片过多会增加集群管理开销和查询的协调成本。

4.2 批量写入父子文档

实际生产中不会一条条写，而是用 bulk API 批量写入。这里有个关键技巧：父文档必须先于子文档写入，否则子文档会因为找不到父文档而报错。bulk 请求里要保证顺序。

POST /shop_parent_child/_bulk?refresh=false {"index":{"_id":"p1"}} {"name":"某款无线耳机","price":299,"category":"数码","relation":{"name":"product"}} {"index":{"_id":"s1","routing":"p1"}} {"sku_name":"黑色标准版","stock":100,"sku_price":299,"relation":{"name":"sku","parent":"p1"}} {"index":{"_id":"s2","routing":"p1"}} {"sku_name":"白色降噪版","stock":50,"sku_price":399,"relation":{"name":"sku","parent":"p1"}} {"index":{"_id":"p2"}} {"name":"某款机械键盘","price":499,"category":"数码","relation":{"name":"product"}} {"index":{"_id":"s3","routing":"p2"}} {"sku_name":"青轴版","stock":30,"sku_price":499,"relation":{"name":"sku","parent":"p2"}}

注意每个子文档的routing都指向了对应的父文档 ID。批量写入时，如果某个子文档的父文档不存在，整条会失败。所以要么保证父文档先写，要么在应用层做重试。

4.3 关联查询实战

现在来几个典型查询。第一个：找出所有有库存大于 80 的 SKU 的商品，并且按库存最高的 SKU 评分排序：

GET /shop_parent_child/_search { "query": { "has_child": { "type": "sku", "query": { "range": { "stock": { "gt": 80 } } }, "score_mode": "max", "inner_hits": { "size": 3, "sort": [{ "stock": "desc" }] } } } }

inner_hits是个好东西，它能在返回父文档的同时，把匹配的子文档也带出来。这样前端展示"商品 + 匹配的 SKU"就很方便，不用再发一次查询。size: 3限制每个父文档最多返回 3 个匹配子文档，避免返回过多数据。

第二个查询：找出所有属于价格大于 300 的商品的 SKU：

GET /shop_parent_child/_search { "query": { "has_parent": { "parent_type": "product", "query": { "range": { "price": { "gt": 300 } } }, "score_mode": "score" } } }

第三个：统计每个类目下有多少个 SKU。这个要用children聚合：

GET /shop_parent_child/_search { "size": 0, "aggs": { "categories": { "terms": { "field": "category" }, "aggs": { "sku_count": { "children": { "type": "sku" } } } } } }

这个聚合会先按类目分桶，然后在每个类目下统计子文档数量。注意children聚合只能统计子文档数量，不能直接对子文档字段求和。要对子文档字段求和，得在children聚合下再嵌套一个terms或stats聚合。

4.4 更新与删除的注意事项

更新子文档很简单，直接按子文档 ID 更新即可，不会影响父文档：

POST /shop_parent_child/_update/s1?routing=p1 { "doc": { "stock": 120 } }

注意 update 也要带 routing，否则找不到文档。删除子文档同理，带 routing 删除。删除父文档时，子文档不会自动删除，会变成"孤儿文档"。ElasticSearch 不会帮你级联删除，这需要在应用层处理。我一般会在删除父文档后，用delete_by_query清理对应的子文档：

POST /shop_parent_child/_delete_by_query { "query": { "has_parent": { "parent_type": "product", "query": { "term": { "_id": "p1" } } } } }

但delete_by_query性能一般，数据量大时慎用。更好的做法是在应用层维护父子关系，删除父文档时同步删除子文档。

5. 常见问题与排查技巧实录

5.1 子文档写入报 "parent missing" 错误

这是最常见的错误，报错信息类似[parent] document is missing。原因通常是父文档还没写入，或者子文档的 routing 写错了，导致它落到了没有父文档的分片。

排查步骤：先确认父文档是否存在，用GET /index/_doc/parent_id查一下。如果父文档存在，再检查子文档的 routing 是否等于父文档 ID。我遇到过一种隐蔽情况：父文档 ID 是数字，子文档 routing 传成了字符串，虽然看起来一样，但哈希结果可能不同。所以 routing 的类型要和父文档 ID 保持一致。

5.2 has_child 查询慢得离谱

父子文档查询慢，通常有几个原因。第一是 global ordinals 没构建好，第一次查询会慢，后续会快。第二是子文档数量太大，join 操作要遍历大量子文档。第三是分片数不合理，导致查询要跨太多分片。

优化手段：控制 refresh 频率，减少 ordinals 重建；给子文档的查询字段加索引；如果只是统计子文档数量，用children聚合比has_child查询快。还有一个技巧：如果业务允许，把不常变的父文档字段冗余到子文档里，减少 join 查询的次数。

5.3 父子文档的评分排序不符合预期

前面提过score_mode的问题。默认none意味着关联文档的评分不影响结果，很多人没注意这个默认值，导致排序和预期不符。如果你希望子文档的匹配度影响父文档排序，必须显式设置score_mode为max、sum等。

另外，has_child查询的评分计算和普通查询不同，它是在父文档层面重新计算的。如果你对排序要求很高，建议用function_score或者把关键排序字段冗余到父文档。

5.4 常见问题速查表

5.5 几个我踩过的坑

第一个坑：一个索引只能有一个 join 字段。我一开始想给商品同时定义"商品-SKU"和"商品-评论"两组关系，以为可以建两个 join 字段，结果直接报错。正确做法是在同一个 join 字段的relations里定义多组关系，比如{"product": ["sku", "review"]}。但这样会让 join 关系变复杂，查询时要注意 type 区分。

第二个坑：父子文档不能跨索引。我曾经想把父文档放一个索引，子文档放另一个索引，结果发现根本行不通。父子文档必须在同一个索引内，这是硬性约束。

第三个坑：reindex 时父子关系会丢。用 reindex API 迁移数据时，如果不带 routing，子文档会散落到不同分片，父子关系断裂。reindex 父子文档必须用脚本处理 routing，或者用 logstash 这类工具保证 routing 正确传递。

提示：如果你的父子文档数据量很大，建议在低峰期做 reindex，并且提前在目标索引建好 mapping。reindex 过程中要监控目标索引的父子关系完整性，可以抽样用 has_parent 查询验证。

6. 父子文档的适用边界与替代方案

父子文档不是万能的，用之前一定要评估清楚。它最适合的场景是：一对多关系、子文档数量大且更新频繁、查询以"从父查子"或"从子查父"为主、对排序和聚合要求不高。典型的就是商品-SKU、订单-明细、文章-评论。

如果你的场景是子文档数量少、更新不频繁、需要复杂的父子联合排序和聚合，那 nested 更合适。如果父子关系非常复杂（多层级、多对多），或者需要跨索引关联，那可能要考虑应用层做关联，或者用宽表冗余的方式。

还有一种情况：如果你的"子文档"其实可以独立存在，不需要强父子语义，那直接拆成两个索引，用应用层做 join 可能更简单。ElasticSearch 的 join 查询毕竟有性能代价，能用简单方案解决就别上复杂方案。

我在实际项目里的体会是：父子文档适合"读多写多、关系简单、查询模式固定"的场景。一旦查询模式变得复杂多变，维护成本会快速上升。所以选型时不要只看功能能不能实现，还要看长期维护成本。数据建模这件事，前期多想一步，后期少踩十个坑。