$map 是 mongodb 聚合管道中对数组元素逐项映射生成新数组的操作符，适用于字段重命名、类型转换、嵌套提取等场景，需配合 $ifnull 等处理 null/空数组边界，并常与 $filter、$reduce 组合使用。
什么是 $map，它适合解决什么问题
$map 是 MongoDB 聚合管道中用于对数组每个元素执行表达式并返回新数组的操作符。它不改变原数组结构，只做“逐项映射”，类似 JavaScript 的 Array.prototype.map()。适合场景包括：字段重命名、类型转换（如字符串转数字）、嵌套字段提取、添加固定前缀/后缀、条件计算等。
常见错误是误把它当过滤器用——$map 本身不删元素，要过滤得配合 $filter；另一个坑是传入空数组或 null 时，结果直接为 null，不是空数组。
使用时必须提供两个参数：input（源数组）和 as（当前元素的变量名），再在 in 中写表达式。变量名不能含点号或美元符，比如 as: "item" 合法，as: "user.name" 会报错。
怎么写一个安全可用的 $map 表达式
关键在于处理边界情况：空数组、null、非数组输入。MongoDB 不会自动跳过或报错，而是让整个字段变成 null，这容易引发下游聚合阶段出错。
{
$map: {
input: { $ifNull: ["$tags", []] },
as: "tag",
in: { $toUpper: "$$tag" }
}
}
这个写法里：
-
$ifNull: ["$tags", []]把null或缺失字段转为空数组，避免$map崩溃 -
$$tag中的双美元符表示引用as定义的变量，单$是字段路径 -
in里可以嵌套任意表达式，但不能写聚合阶段（如$group），也不能访问其他文档字段（除非用$let显式绑定）
如果想把字符串数组转成对象数组，比如 ["a", "b"] → [{name: "a"}, {name: "b"}]，就写：
in: { name: "$$tag" }
和其他数组操作符组合使用的典型模式
$map 单独用较少，常和 $filter、$reduce 配合完成更复杂的数组处理。
-
先过滤再映射（避免对无意义元素做无效计算）：
{ $map: { input: { $filter: { input: "$scores", cond: { $gt: ["$$this", 0] } } }, as: "score", in: { value: "$$score", level: { $cond: [{ $gt: ["$$score", 90] }, "A", "B"] } } } } -
和
$reduce连用实现“映射 + 归约”：比如统计每个标签的长度总和{ $reduce: { input: { $map: { input: "$tags", as: "t", in: { $strLenCP: "$$t" } } }, initialValue: 0, in: { $add: ["$$value", "$$this"] } } }
注意：$map 输出仍是数组，若后续阶段（如 $group）需要标量值，必须再用 $arrayElemAt、$size 或 $reduce 拆解。
性能和兼容性要注意的几个点
$map 是内存内操作，数组越大越吃内存，尤其当 in 表达式涉及复杂计算（如正则、嵌套 $cond）时，性能下降明显。生产环境建议控制输入数组长度在几千以内。
- MongoDB 3.4+ 支持
$map，但 3.4–3.6 不支持在$facet内部使用$$ROOT引用顶层字段，升级到 4.0+ 更稳妥 - 如果数组元素本身是文档，且你想提取其中某个字段组成新数组（比如
users: [{name:"a"},{name:"b"}] → ["a","b"]），最简写法就是in: "$$this.name"，别绕路用$getField - 在 Atlas Search 或聚合管道中使用时，
$map的表达式不能包含全文搜索操作符（如$search），否则会报invalid expression
真正容易被忽略的是：当 input 字段类型不是数组时（比如是字符串或数字），$map 不会报错，而是静默返回 null。上线前务必用 $isArray 做断言校验，或者统一用 $cond 包一层兜底逻辑。
