arrayFilters必须作为update方法的第三个参数(options对象)传入,不能写在query或update文档中;每个$\[x\]占位符需严格对应一个大小写敏感的arrayFilters条件,且父级字段存在性须在query中用$exists和$ne: null显式校验。

arrayFilters 必须作为 update 操作的第三参数传入
只在 $set 路径里写 $[i] 是无效的,MongoDB 不报错但字段根本不会更新。它只是个占位符,必须靠 arrayFilters 选项激活。
常见错误是把 arrayFilters 写进 query 或 update 字段里,比如:{ $set: { "items.$[i].status": "done" }, arrayFilters: [...] } —— 这会直接被忽略。正确位置是 update 方法的 options 对象:
db.orders.updateOne(
{ _id: orderId },
{ $set: { "items.$[i].status": "done" } },
{ arrayFilters: [{ "i.status": "pending" }] }
)
-
arrayFilters是 update 操作的第三个参数(options),不是 update 文档的一部分 - 每个
$[x]必须有且仅有一个arrayFilters条件与之严格对应,变量名大小写敏感 - 如果用了
$[i]却漏传arrayFilters,操作静默失败,日志里也看不到提示
双层嵌套数组不能用 $[a].$[b] 语法
MongoDB 不支持 activities.steps[].logs[] 这种结构下直接写 "activities.$[a].steps.$[s].logs.$[l].msg" —— 语法错误,驱动会抛 InvalidPathError。
必须拆成两步:先定位外层数组项,再在 $set 路径中用点号访问其子数组,并为子数组单独声明 $[l] 占位符 + 对应过滤条件:
db.logs.updateOne(
{ _id: logId, "activities.name": "deploy" },
{
$set: {
"activities.$[a].steps.$[s].logs.$[l].processed": true
}
},
{
arrayFilters: [
{ "a.name": "deploy" },
{ "s.type": "build" },
{ "l.timestamp": { $gt: ISODate("2026-10-20") } }
]
}
)
- 路径必须逐层展开:
activities.$[a].steps.$[s].logs.$[l].processed,不能跳过steps - 三个
$[x]就要配三个arrayFilters条件,顺序无关但变量名必须一一对应 - 如果某层字段(如
steps)可能为null或缺失,该文档会被整个跳过,不更新也不报错
父级字段存在性必须在 query 中显式校验
arrayFilters 只管数组内部过滤,不管外层字段是否存在。如果 user.profile.skills 是 null 或字段根本不存在,$[s] 就找不到任何元素,更新静默失效。
务必在 query 条件里确认父级路径真实存在:
db.users.updateMany(
{
_id: userId,
"user.profile": { $exists: true },
"user.profile.skills": { $exists: true, $ne: null }
},
{ $set: { "user.profile.skills.$[s].level": "senior" } },
{ arrayFilters: [{ "s.name": "MongoDB" }] }
)
- 不要依赖
$set自动创建中间对象 —— 它会创建空profile或skills,可能违背业务语义 - 若需“有则更新、无则跳过”,必须用
$exists+$ne: null组合,单用$exists不够(因为字段可能存了null) - 点号路径中任意一级为
null或缺失,整个$set路径就失效,且无提示
更新数组元素时别硬写索引,比如 "items.0.title"
$set: { "items.0.title": "x" } 看似简单,但在生产环境极危险:数组顺序一变、元素被删、或并发写入,就更新错对象。
真正安全的做法是用条件匹配而非位置假设:
- 单层数组且只需改第一个匹配项 → 用
$:"items.$.title"+ 查询条件带"items.status": "draft" - 单层数组需改所有匹配项 → 用
$[]或$[i]+arrayFilters - 多层嵌套 → 只能用
$[a]+arrayFilters,且每层都要声明、每层都要校验存在性
最常被忽略的一点:arrayFilters 的条件作用域仅限于当前数组层级,它不会穿透到父文档字段。想同时约束外层文档和内层数组,得把外层条件写进 query,内层条件写进 arrayFilters —— 两者缺一不可。











