Docs 菜单
Docs 主页
/
MongoDB Manual
/ / /

db.collection.insert()

在此页面上

  • 定义
  • 语法
  • 行为
  • 示例
  • WriteResult
  • BulkWriteResult

重要

已弃用的 mongosh 方法

此方法在 mongosh 中已弃用。有关替代方法,请参阅与旧版 mongo Shell 的兼容性更改

db.collection.insert()

将一个或多个文档插入集合中。

返回:
  • 单次插入的 WriteResult 对象。

  • 用于批量插入操作的 BulkWriteResult 对象。

insert() 方法使用的语法如下:

db.collection.insert(
<document or array of documents>,
{
writeConcern: <document>,
ordered: <boolean>
}
)
Parameter
类型
说明

document

文档或数组

要插入到集合中的文档或文档数组。

writeConcern

文档

可选。表达 写关注(write concern)的文档。省略使用默认写关注(write concern)。请参阅写关注。

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

ordered

布尔

可选。如果为 true,则对数组中的文档执行有序插入,如果其中一个文档发生错误,MongoDB 将返回,而不处理数组中的其余文档。

如果为 false,则执行无序插入,如果其中一个文档发生错误,则继续处理数组中的其余文档。

默认值为 true

insert() 会返回包含此操作状态的对象。

insert() 方法使用 insert 命令,该命令使用默认的写关注。要指定不同的写关注,请将写关注包含在 options 参数中。

如果集合不存在,则 insert() 方法将创建集合。

如果文档没有指定 _id 字段,那么 MongoDB 将添加 _id 字段,并在插入前为文档分配唯一的 ObjectId() 字段。 大多数驱动程序都会创建一个 ObjectId 并插入 _id 字段,但如果驱动程序或应用程序没有这样做,则 mongod 将创建并填充 _id

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

db.collection.insert() 可以在分布式事务中使用。

重要

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

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

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

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

提示

另请参阅:

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

如果 db.collection.insert() 操作成功插入文档,则该操作会为 oplog (操作日志)添加一个条目。如果操作失败,则该操作不会为 oplog 添加条目。

以下示例会将文档插入到 products 集合。如果集合不存在,insert() 方法会创建该集合。

在下面的示例中,传递给 insert() 方法的文档不包含 _id 字段:

db.products.insert( { item: "card", qty: 15 } )

在插入过程中,mongod 会创建 _id 字段并为其分配唯一的 ObjectId() 值,该值由插入的文档验证:

{ "_id" : ObjectId("5063114bd386d8fadbd6b004"), "item" : "card", "qty" : 15 }

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

在以下示例中,传递给 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 } }
)

传递单个文档时,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 }"
}
})

传递文档数组时,insert() 会返回 BulkWriteResult() 对象。有关详细信息,请参阅 BulkWriteResult()

后退

db.collection.hideIndex