db. 集合.insertOne()（mongosh方法）

带驱动程序的 MongoDB

本页面文档 mongosh 方法。要查看 MongoDB 驱动程序中的等效方法，请参阅您的编程语言的相应页面：

C#Java Sync Node.js PyMongo C C++Go Java RS Kotlin Coroutine Kotlin Sync PHP Mongoid Rust Scala

定义

db.collection.insertOne()

将单个文档插入集合。

返回：	文档包含以下内容：如果操作使用写关注来运行，则 `acknowledged` 布尔值为 `true`；如果已禁用写关注，则为 `false`。包含已插入文档的 `_id` 值的字段 `insertedId`。

兼容性

此方法可用于以下环境中托管的部署：

MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

注意

This command is supported in all MongoDB Atlas clusters. For information on Atlas support for all commands, see Unsupported Commands.

MongoDB Enterprise：基于订阅、自我管理的 MongoDB 版本
MongoDB Community：源代码可用、免费使用且可自行管理的 MongoDB 版本

语法

db.collection.insertOne() 采用以下形式：

db.collection.insertOne(
    <document>,
    {
      writeConcern: <document>
    }
)

参数

insertOne() 使用以下参数：

Parameter	类型	说明
`document`	文档	要插入到集合中的文档。
`writeConcern`	文档	可选。表达写关注的文档。省略以使用默认写关注。如果是在事务中运行，则请勿显式设置此操作的写关注。要将写关注与事务一起使用，请参阅事务和写关注。

行为

集合与`_id`字段创建

如果该集合不存在，则insertOne()会创建该集合。

如果文档未指定 _id 字段，则 mongod 会添加 _id 字段，并为该文档分配唯一的 ObjectId()。大多数驱动程序都会创建一个 ObjectId 并插入 _id 字段，如果驱动程序或应用程序不这样做，则 mongod 将创建并填充 _id。

如果文档包含 _id 字段，则 _id 值在集合中必须是唯一的，以避免重复键错误。

可解释性

insertOne() 与db.collection.explain() 不兼容。

Error Handling

如果出错，insertOne() 会引发 writeError 或 writeConcernError 异常。

模式验证错误

如果您的集合使用模式验证并将 validationAction 设置为error ，则插入无效文档会引发 MongoServerError 且 insertOne() 会失败。

事务

insertOne() 可用于分布式事务。

重要

在大多数情况下，与单文档写入操作相比，分布式事务会产生更高的性能成本，并且分布式事务的可用性不应取代有效的模式设计。在许多情况下，非规范化数据模型（嵌入式文档和数组）仍然是数据和使用案例的最佳选择。换言之，对于许多场景，适当的数据建模将最大限度地减少对分布式事务的需求。

有关其他事务使用注意事项（如运行时间限制和 oplog 大小限制），另请参阅生产注意事项。

在事务中创建集合

如果分布式事务不是跨分片写入事务，则可以在该事务中创建集合和索引。

如果在事务中对不存在的集合指定插入操作，则 MongoDB 会隐式创建该集合。

写关注和事务

如果是在事务中运行，则请勿显式设置此操作的写关注。要将写关注与事务一起使用，请参阅事务和写关注。

Oplog 条目

如果 insertOne() 操作成功插入文档，则该操作会为 oplog（操作日志）添加一个条目。如果操作失败，则该操作不会为 oplog 添加条目。

示例

本页上的示例使用来自 sample_mflix 数据集的数据。有关如何将此数据集加载到您的自管理 MongoDB 部署中的详细信息，请参阅加载示例数据集。如果您对示例数据库进行了任何修改，您可能需要删除并重新创建数据库，才能运行此页面上的示例。

插入文档而不指定 `_id` 字段

以下示例将一个没有 _id 字段的文档插入到 movies 集合中：

db.movies.insertOne( { title: "Inception", year: 2010, genres: [ "Action", "Sci-Fi" ] } )

{
  acknowledged: true,
  insertedId: "..."
}

由于文档不包含 _id，因此 mongod 会创建并添加 _id 字段，并为其分配唯一的 ObjectId() 值。

ObjectId 值特定于运行操作时的设备和时间。因此，您的值可能与示例中的值不同。

插入文档并指定 `_id` 字段

如果您在插入文档时指定 _id，则 _id 值在集合中必须是唯一的。以下示例将文档插入 movies 集合并指定 _id：

db.movies.insertOne( { _id: 10, title: "Inception", year: 2010 } )

{ acknowledged: true, insertedId: 10 }

为属于唯一索引的任何键插入重复值（例如 _id）会引发异常。下面的例子中尝试插入一个已存在 _id 值的文档：

try {
   db.movies.insertOne( { _id: 10, title: "Inception", year: 2010 } );
} catch (e) {
   print (e);
}

由于 _id: 10 已存在，因此会抛出以下异常：

WriteError({
   "index" : 0,
   "code" : 11000,
   "errmsg" : "E11000 duplicate key error collection: sample_mflix.movies index: _id_ dup key: { : 10.0 }",
   "op" : {
      "_id" : 10,
      "title" : "Inception",
      "year" : 2010
   }
})

增加写关注

给定一个三节点副本集，以下操作指定 w 为 majority，指定 wtimeout 为 100：

try {
   db.movies.insertOne(
       { title: "Arrival", year: 2016 },
       { writeConcern: { w : "majority", wtimeout : 100 } }
   );
} catch (e) {
   print (e);
}

如果确认花费的时间超过wtimeout限制，则会引发以下异常：

WriteConcernError({
   "code" : 64,
   "errmsg" : "waiting for replication timed out",
   "errInfo" : {
     "wtimeout" : true,
     "writeConcern" : {
       "w" : "majority",
       "wtimeout" : 100,
       "provenance" : "getLastErrorDefaults"
     }
   }
})

后退

db.collection.insertMany

来年

db.collection.isCapped