$setOnInsert（插入时设置）

最后更新：2026-10-09

$setOnInsert（插入时设置）

$setOnInsert 只在 upsert 触发插入新文档时设置字段值；若匹配到已有文档，该操作符被忽略。`{ $setOnInsert: { createdAt: new Date() } }`。常与 upsert: true 配合记录文档创建时间、初始化默认值，实现「有则不动、无则初始化」的语义。

📝 语法

{ $setOnInsert: { <字段>: <值> } }

⚙️ 参数

返回值：更新结果文档

▶ 示例

请在本地安装的 mongosh 中执行以下命令（需已启动 mongod）：

// $setOnInsert：新文档才写入 createdAt
// 已有文档更新时被忽略
db.users.updateOne(
  { email: 'alice@example.com' },
  {
    $set: { name: 'Alice' },
    $setOnInsert: { createdAt: new Date() }
  },
  { upsert: true }
)

运行结果：

// 首次插入时 createdAt 被记录；后续更新不会改动它

📌 注意事项

• 只在 upsert 插入时生效
• 与 $set 同文档使用，初始化与更新各司其职
• 适合维护 createdAt 等不可变字段

🏷️ 相关标签

💡 相关案例

📚 相关教程

❓ 常见问题

Web-Tutorial 技术团队

由多位开发者共同维护的编程教程平台。每篇教程由对应领域的开发者编写和审核，确保内容准确可靠。如发现任何问题，欢迎向我们反馈。

关于我们