MongoDB-CN-Manual
搜索文档…
db.collection.insert()
在本页面

定义

  • db.collection. insert ()
    • 将一个或多个文档插入集合中。
insert()方法具有以下语法:
1
db.collection.insert(
2
<document or array of documents>,
3
{
4
writeConcern: <document>,
5
ordered: <boolean>
6
}
7
)
Copied!
参数
类型
描述
document
文件或 array
要插入集合的文档或 array 文档。
writeConcern
writeConcern
可选的。表示写关注的文件。省略使用默认写入问题。见写关注。 version 2.6 中的新内容。
ordered
boolean
可选的。如果true,则在 array 中执行文档的有序插入,如果其中一个文档发生错误,MongoDB 将 return 而不处理 array 中的其余文档。 如果false,执行无序的 insert,如果其中一个文档发生错误,继续处理 array 中的其余文档。 默认为true
更改 version 2.6:insert()返回包含操作状态的 object。
返回:
单个插入的写结果 object。 ABulkWriteResult object 用于批量插入。

行为

写关注

insert()方法使用插入命令,该命令使用默认的写关注。要指定其他写入问题,请在 options 参数中包含写入关注点。

创建集合

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

_id 字段

如果文档未指定_id字段,则 MongoDB 将添加_id字段,并在插入之前为文档指定唯一的ObjectId。大多数驱动程序创建一个 ObjectId 并插入_id字段,但如果驱动程序或 application 没有,则mongod将创建并填充_id
如果文档包含_id字段,则_id value 在集合中必须是唯一的,以避免重复的 key 错误。

事务

db.collection.insert()可以在多文档交易中使用。
集合必须已经存在。事务中不允许执行会导致创建新集合的插入操作。
如果在事务中运行,请不要为操作明确设置写关注点。要对事务使用写关注,请参见 事务和写关注。
重要
在大多数情况下,与单文档写入相比,多文档事务产生的性能成本更高,并且多文档事务的可用性不应替代有效的架构设计。在许多情况下, 非规范化数据模型(嵌入式文档和数组)将继续是您的数据和用例的最佳选择。也就是说,在许多情况下,适当地对数据建模将最大程度地减少对多文档交易的需求。
有关其他事务使用方面的注意事项(例如运行时限制和操作日志大小限制),另请参见 生产注意事项。

例子

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

插入文档而不指定_id 字段

在以下 example 中,传递给insert()方法的文档不包含_id字段:
1
db.products.insert( { item: "card", qty: 15 } )
Copied!
在 insert 期间,mongod将创建_id字段并为其分配唯一的ObjectId value,由插入的文档验证:
1
{ "_id" : ObjectId("5063114bd386d8fadbd6b004"), "item" : "card", "qty" : 15 }
Copied!
当操作为 run 时,ObjectId值特定于机器和 time。因此,您的值可能与 example 中的值不同。

插入指定_id 字段的文档

在下面的示例中,传递给insert()方法的文档包含_id字段。 _id的 value 在集合中必须是唯一的,以避免重复的 key 错误。
1
db.products.insert( { _id: 10, item: "box", qty: 20 } )
Copied!
该操作在products集合中插入以下文档:
1
{ "_id" : 10, "item" : "box", "qty" : 20 }
Copied!

插入多个文档

以下 example 通过将 array 文档传递给insert()方法来执行三个文档的批量插入。默认情况下,MongoDB 执行有序的 insert。对于有序插入,如果在其中一个文档的 insert 期间发生错误,MongoDB 将返回错误而不处理 array 中的其余文档。
array 中的文档不需要具有相同的字段。例如,array 中的第一个文档有一个_id字段和一个type字段。由于第二个和第三个文档不包含_id字段,mongod将在 insert 期间为第二个和第三个文档创建_id字段:
1
db.products.insert(
2
[
3
{ _id: 11, item: "pencil", qty: 50, type: "no.2" },
4
{ item: "pen", qty: 20 },
5
{ item: "eraser", qty: 25 }
6
]
7
)
Copied!
该操作插入了以下三个文件:
1
{ "_id" : 11, "item" : "pencil", "qty" : 50, "type" : "no.2" }
2
{ "_id" : ObjectId("51e0373c6f35bd826f47e9a0"), "item" : "pen", "qty" : 20 }
3
{ "_id" : ObjectId("51e0373c6f35bd826f47e9a1"), "item" : "eraser", "qty" : 25 }
Copied!

执行无序 Insert

以下 example 执行三个文档的无序插入。对于无序插入,如果在其中一个文档的 insert 期间发生错误,MongoDB 将继续插入 array 中的其余文档。
1
db.products.insert(
2
[
3
{ _id: 20, item: "lamp", qty: 50, type: "desk" },
4
{ _id: 21, item: "lamp", qty: 20, type: "floor" },
5
{ _id: 22, item: "bulk", qty: 100 }
6
],
7
{ ordered: false }
8
)
Copied!

覆盖默认写入关注

对副本集的以下操作指定"w: majority""w: majority",其wtimeout为 5000 毫秒,以便该方法在写入传播到大多数表决副本集成员后返回,或者该方法在 5 秒后超时。
在 version 3.0 中更改:在以前的版本中,majority指的是副本集的大多数成员而不是大多数投票成员。
1
db.products.insert(
2
{ item: "envelopes", qty : 100, type: "Clasp" },
3
{ writeConcern: { w: "majority", wtimeout: 5000 } }
4
)
Copied!

写结果

传递单个文档时,insert()返回WriteResult object。

成功的结果

insert()返回包含操作状态的写结果 object。成功后,写结果 object 包含有关插入文档数量的信息:
1
WriteResult({ "nInserted" : 1 })
Copied!

写关注错误

如果insert()方法遇到写入关注错误,则结果包括WriteResult.writeConcernError字段:
1
WriteResult({
2
"nInserted" : 1,
3
"writeConcernError" : {
4
"code" : 64,
5
"errmsg" : "waiting for replication timed out at shard-a"
6
}
7
})
Copied!

与写关注无关的错误

如果insert()方法遇到 non-write 关注错误,则结果包括WriteResult.writeError字段:
1
WriteResult({
2
"nInserted" : 0,
3
"writeError" : {
4
"code" : 11000,
5
"errmsg" : "insertDocument :: caused by :: 11000 E11000 duplicate key error index: test.foo.$_id_ dup key: { : 1.0 }"
6
}
7
})
Copied!

BulkWriteResult

传递 array 文档时,insert()返回BulkWriteResult() object。有关详细信息,请参阅BulkWriteResult()。
译者:李冠飞
校对:
最近更新 1mo ago