$graphLookup（图关联）
最后更新：2026-10-09
$graphLookup（图关联）
$graphLookup 在集合上做递归查找，模拟图遍历：从每条文档的 connectFromField 值出发，递归匹配 connectToField，直到 maxDepth 或不再有匹配，结果存入 as 字段。适合组织架构、分类树、路由跳数等场景。与 $lookup 不同，它能跨任意层级递归。
| 分类 | 高级与诊断 |
|---|---|
| MongoDB 版本 | 1.0+ |
| 示例语言 | mongosh (Shell) |
📝 语法
{ $graphLookup: { from: "<集合名>", startWith: <表达式>, connectFromField: "<字段>", connectToField: "<字段>", as: "<输出字段>", maxDepth: <数字>, depthField: "<深度字段>" } }⚙️ 参数
| from | 要递归查找的目标集合。 |
|---|---|
| startWith | 递归起点的值表达式。 |
| connectFromField | 当前文档中携带匹配值的字段。 |
| connectToField | 目标集合中被匹配的字段。 |
| as | 递归结果写入的字段名。 |
| maxDepth | 最大递归层数，省略表示无限制。 |
返回值：每条文档附加递归结果数组
▶ 示例
请在本地安装的 mongosh 中执行以下命令（需已启动 mongod）：
// $graphLookup：找每个员工的上级链
db.employees.aggregate([
{ $graphLookup: {
from: 'employees',
startWith: '$reportsTo',
connectFromField: 'reportsTo',
connectToField: 'name',
as: 'chain'
} }
])运行结果：
// 每条员工文档带 chain 递归上级数组📌 注意事项
- connectToField 上应有索引以加速递归
- 结果只包含递归匹配到的文档，不包含起始文档自身
- maxDepth 为 0 表示只匹配一层
🏷️ 相关标签
💡 相关案例
更多实战案例即将上线，敬请期待。
📚 相关教程
❓ 常见问题
Q$graphLookup 和 $lookup 有什么区别？
A$lookup 只做一层关联；$graphLookup 递归遍历多层级关系。
Q递归会无限循环吗？
A会持续到没有匹配为止，可用 maxDepth 限制层数。
Q结果包含自己吗？
A不包含，startWith 是查找起点，结果是与之匹配的其他文档。
