MongoDB 聚合查询：精准提取嵌套数组中所有匹配项及其父文档

本文详解如何使用 mongodb 聚合管道（`$unwind` + `$match` + `$group`）完整保留嵌套数组中**所有满足正则匹配的子文档**，并正确重组为原始结构，避免因误用 `$replaceroot` 或 `$mergeobjects` 导致的单元素数组问题。

在处理如 pictures 这类嵌套数组时，常见误区是：先 $unwind 展开，再 $match 筛选，最后试图通过 $addToSet 或 $push 汇总匹配项——但若后续错误地引入 $replaceRoot 与 $mergeObjects，极易破坏数据聚合逻辑，导致每个 _id 组只保留一个匹配项（实际是 $first 取值覆盖了多匹配场景）。

核心问题在于原管道中这段逻辑：

{"$group": { "_id": "$_id", ... "root": {"$first": "$$ROOT"} }},
{"$replaceRoot": { "newRoot": { "$mergeObjects": ["$root", {"pictures": "$pictures"}] }}}

它本质是「先按 _id 分组 → 取任意一条原始文档（$first: "$$ROOT"）→ 再强行合并 pictures 数组」。但由于 $first: "$$ROOT" 是非确定性取值（且未保证该文档的 pictures 字段与当前匹配项关联），最终 $mergeObjects 实际只注入了 $addToSet 聚合后的 pictures，而 $$ROOT 中的原始 pictures 已被 $unwind 破坏，造成语义混淆和结果截断。

✅ 正确解法是彻底剥离对原始根文档的依赖，仅聚合所需字段：

• 使用 {"_id": {"$toString": "$_id"}} 显式转换 _id 类型（适配 JSON 序列化）；
• 用 $first 安全提取 url 和 source（它们在同 _id 文档中恒定）；
• 用 $push（非 $addToSet）收集所有匹配的 pictures 子文档（$addToSet 会去重，但此处需保留重复 name 的不同 version）；

优化后的聚合管道如下：

pipeline = [
    {"$unwind": "$pictures"},
    {"$match": {"pictures.name": {"$regex": pattern}}},
    {"$group": {
        "_id": {"$toString": "$_id"},
        "url": {"$first": "$url"},
        "source": {"$first": "$source"},
        "pictures": {"$push": "$pictures"}  # ✅ 关键：用 $push 保留全部匹配项
    }},
    {"$project": {
        "_id": 1,
        "url": 1,
        "source": 1,
        "pictures": 1
    }}
]

⚠️ 注意事项：

• 勿混用 $addToSet 与 $push：$addToSet 适用于去重场景（如 name 唯一），但本例中同一 name 可能有多个 version（如 "pines" 出现在不同文档中），必须用 $push；
• 避免 $replaceRoot + $$ROOT：$$ROOT 在 $unwind 后已不包含原始嵌套结构，强行合并反而引入不确定性；
• $toString 提前转换 _id：防止 ObjectId 在 JSON 序列化时报错，比后期 {"_id": {"$toString": "$_id"}} 更清晰；
• 若需支持大小写敏感/模糊匹配，可扩展正则标志（如 re.DOTALL）或改用 $text 索引（需提前建全文索引）。

最终返回结果将严格符合预期：每个匹配的顶层文档（_id）下，pictures 数组完整包含该文档内所有 name 匹配查询字符串的子对象，结构清晰、语义准确，可直接用于前端渲染或下游处理。