$setField（动态设字段）
最后更新：2026-10-09
$setField（动态设字段）
$setField在文档中新增或更新指定字段，返回新文档，不修改原文档。语法为{ $setField: { field: 字段名, input: 文档, value: 表达式 } }，field支持动态表达式。value为null时删除该字段。常用于字段名含特殊字符、需要动态字段名的场景。input为null或缺失时返回null。注意$setField与$set阶段不同：它可在表达式嵌套中修改文档，且支持动态字段名。
| 分类 | 字面·变量·对象 |
|---|---|
| MongoDB 版本 | 5.0+ |
| 示例语言 | mongosh (Shell) |
📝 语法
{ $setField: { field: <字段名>, input: <文档表达式>, value: <表达式> } }⚙️ 参数
| field | 要设置的字段名字符串或解析为字符串的表达式。 |
|---|---|
| input | 目标文档，为null或缺失时返回null。 |
| value | 要设置的字段值；为null时删除该字段。 |
返回值：修改后的新文档；input为null或缺失时返回null
▶ 示例
请在本地安装的 mongosh 中执行以下命令（需已启动 mongod）：
// $setField：为每个订单添加税率字段
db.orders.aggregate([
{ $project: {
doc: { $setField: { field: 'taxRate', input: '$$CURRENT', value: 0.08 } }
} }
])运行结果：
{ '_id': 1, 'doc': { '_id': 1, 'price': 100, 'taxRate': 0.08 } }
{ '_id': 2, 'doc': { '_id': 2, 'price': 50, 'taxRate': 0.08 } }📌 注意事项
- 返回新文档，原文档不被修改
- value为null时删除该字段
- 与$getField成对使用，支持动态字段名
🏷️ 相关标签
💡 相关案例
更多实战案例即将上线，敬请期待。
📚 相关教程
❓ 常见问题
Q$setField会修改原文档吗？
A不会，聚合管道中文档不可变，$setField返回新文档。
Q$setField怎么删除字段？
A把value设为null，该字段即被删除。
Q$setField和$set阶段有什么区别？
A$set只能处理静态字段名，$setField支持动态字段名并可用在嵌套表达式中。
