$addFields（添加字段）
最后更新：2026-10-09
$addFields（添加字段）
$addFields 给每个文档新增字段或覆盖已有字段，同时保留其他所有字段。它与 $project 的区别在于：$project 默认丢弃未列出的字段，$addFields 只增不改结构。新字段的值可用任意聚合表达式计算，也常与 $lookup 的关联结果配合使用。从 MongoDB 3.4 起，$set 与它完全等价。
| 分类 | 核心阶段 |
|---|---|
| MongoDB 版本 | 1.0+ |
| 示例语言 | mongosh (Shell) |
📝 语法
{ $addFields: { <新字段>: <表达式>, ... } }⚙️ 参数
| 新字段 | 字段名映射为聚合表达式，表达式引用输入文档的已有字段。 |
|---|
返回值：新增或覆盖字段后的文档流
▶ 示例
请在本地安装的 mongosh 中执行以下命令（需已启动 mongod）：
// $addFields：新增总价字段
db.sales.aggregate([
{ $addFields: { total: { $multiply: ['$price', '$qty'] } } }
])运行结果：
// 原字段全部保留，多了 total
{ "item": "Pen", "price": 50, "qty": 3, "total": 150 }📌 注意事项
- $addFields 不会删除任何原字段
- 字段名可用点号路径写内嵌字段，如 'order.amount'
- 同一阶段内不能引用本阶段刚定义的字段
🏷️ 相关标签
💡 相关案例
📚 相关教程
❓ 常见问题
Q$addFields 和 $set 有什么区别？
A从 MongoDB 3.4 起两者完全等价，$addFields 是更早的名称，可互换使用。
Q$addFields 能引用新字段吗？
A不能，同一阶段的表达式只能引用输入文档已有的字段，需要时可用多个 $addFields 串联。
Q$addFields 会覆盖已有字段吗？
A会，字段名与已有字段相同时直接覆盖其值。
