db.collection.insert()
定义
db.collection.insert()将一个或多个文档插入集合中。
返回： 单次插入的 WriteResult 对象。
用于批量插入操作的 BulkWriteResult 对象。
兼容性
可以使用 db.collection.Insert() 查找托管在以下环境中的部署：
MongoDB Atlas：用于云中 MongoDB 部署的完全托管服务
MongoDB Enterprise：基于订阅、自我管理的 MongoDB 版本
MongoDB Community：源代码可用、免费使用且可自行管理的 MongoDB 版本
语法
insert() 方法使用的语法如下：
db.collection.insert( <document or array of documents>, { writeConcern: <document>, ordered: <boolean> } )
Parameter | 类型 | 说明 |
|---|---|---|
document | 文档或数组 | 要插入到集合中的文档或文档数组。 |
writeConcern | 文档 | |
ordered | 布尔 | 可选。如果为 如果为 默认值为 |
insert() 会返回包含此操作状态的对象。
行为
写关注
insert() 方法使用 insert 命令，该命令使用默认的写关注。要指定不同的写关注，请将写关注包含在 options 参数中。
创建集合
如果集合不存在，则 insert() 方法将创建集合。
_id 字段
如果文档没有指定 _id 字段，那么 MongoDB 将添加 _id 字段，并在插入前为文档分配唯一的 ObjectId() 字段。 大多数驱动程序都会创建一个 ObjectId 并插入 _id 字段，但如果驱动程序或应用程序没有这样做，则 mongod 将创建并填充 _id。
如果文档包含 _id 字段，则 _id 值在集合中必须是唯一的，以避免重复键错误。
事务
db.collection.insert() 可以在分布式事务中使用。
重要
在大多数情况下，与单文档写入操作相比，分布式事务会产生更高的性能成本，并且分布式事务的可用性不应取代有效的模式设计。在许多情况下，非规范化数据模型（嵌入式文档和数组）仍然是数据和使用案例的最佳选择。换言之，对于许多场景，适当的数据建模将最大限度地减少对分布式事务的需求。
有关其他事务使用注意事项（如运行时间限制和 oplog 大小限制），另请参阅生产注意事项。
在事务中创建集合
如果事务不是跨分片写事务，则可以在分布式事务中创建集合和索引。
如果在事务中对不存在的集合指定插入操作，则 MongoDB 会隐式创建该集合。
写关注和事务
如果是在事务中运行，则请勿显式设置此操作的写关注。要将写关注与事务一起使用，请参阅事务和写关注。
Oplog 条目
如果 db.collection.insert() 操作成功插入文档，则该操作会为 oplog （操作日志）添加一个条目。如果操作失败，则该操作不会为 oplog 添加条目。
示例
以下示例会将文档插入到 products 集合。如果集合不存在，insert() 方法会创建该集合。
插入文档而不指定 字段_id
在下面的示例中，传递给 insert() 方法的文档不包含 _id 字段：
db.products.insert( { item: "card", qty: 15 } )
在插入过程中，mongod 会创建 _id 字段并为其分配唯一的 ObjectId() 值，该值由插入的文档验证：
{ "_id" : ObjectId("5063114bd386d8fadbd6b004"), "item" : "card", "qty" : 15 }
ObjectId 值特定于运行操作时的设备和时间。因此，您的值可能与示例中的值不同。
插入指定 字段的文档_id
在以下示例中，传递给 insert() 方法的文档包含 _id 字段。_id 的值在集合中必须是唯一的，以避免出现重复键错误。
db.products.insert( { _id: 10, item: "box", qty: 20 } )
该操作将以下文档插入到 products 集合中：
{ "_id" : 10, "item" : "box", "qty" : 20 }
插入多个文档
下面的示例通过向 insert() 方法传递一组文档，批量插入了三个文档。默认情况下，MongoDB 执行有序插入。使用有序插入时，如果在插入其中一个文档期间发生错误，MongoDB 将返回错误，而不处理组中的其余文档。
数组中的文档无需具有相同的字段。例如，数组中的第一个文档具有 _id 字段和 type 字段。由于第二和第三个文档不包含 _id 字段，因此 mongod 将在插入过程中为第二个和第三个文档创建 _id 字段：
db.products.insert( [ { _id: 11, item: "pencil", qty: 50, type: "no.2" }, { item: "pen", qty: 20 }, { item: "eraser", qty: 25 } ] )
该操作插入了以下三个文档：
{ "_id" : 11, "item" : "pencil", "qty" : 50, "type" : "no.2" } { "_id" : ObjectId("51e0373c6f35bd826f47e9a0"), "item" : "pen", "qty" : 20 } { "_id" : ObjectId("51e0373c6f35bd826f47e9a1"), "item" : "eraser", "qty" : 25 }
执行无序插入
以下示例无序插入三个文档。对于无序插入，如果在插入其中一个文档的过程中出现错误，MongoDB 会继续插入数组中剩余的文档。
db.products.insert( [ { _id: 20, item: "lamp", qty: 50, type: "desk" }, { _id: 21, item: "lamp", qty: 20, type: "floor" }, { _id: 22, item: "bulk", qty: 100 } ], { ordered: false } )
覆盖默认写关注
以下对副本集的操作指定了写关注 w: 2，其 wtimeout 为 5000 毫秒。该操作要么在写操作传播到主节点和一个辅助节点后返回，要么在 5 秒后超时。
db.products.insert( { item: "envelopes", qty : 100, type: "Clasp" }, { writeConcern: { w: 2, wtimeout: 5000 } } )
WriteResult
传递单个文档时，insert() 会返回 WriteResult 对象。
成功结果
insert() 返回一个包含该操作状态的 WriteResult() 对象。成功后，WriteResult() 对象将包含有关所插入文档数量的信息：
WriteResult({ "nInserted" : 1 })
写关注错误
如果 insert() 方法遇到写关注错误，结果将包括 WriteResult.writeConcernError 字段：
WriteResult({ "nInserted" : 1, "writeConcernError"({ "code" : 64, "errmsg" : "waiting for replication timed out", "errInfo" : { "wtimeout" : true, "writeConcern" : { "w" : "majority", "wtimeout" : 100, "provenance" : "getLastErrorDefaults" } } })
与写关注无关的错误
如果 insert() 方法遇到非写关注错误，则结果将包括 WriteResult.writeError 字段：
WriteResult({ "nInserted" : 0, "writeError" : { "code" : 11000, "errmsg" : "insertDocument :: caused by :: 11000 E11000 duplicate key error index: test.foo.$_id_ dup key: { : 1.0 }" } })
BulkWriteResult
传递文档数组时，insert() 会返回 BulkWriteResult() 对象。有关详细信息，请参阅 BulkWriteResult()。