db.collection.insert()

在本页面

• 定义

• 行为

• 例子

• 写结果

• BulkWriteResult

定义

• db.collection. insert ()

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

insert()方法具有以下语法：

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

参数	类型	描述
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字段：

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

在 insert 期间，mongod将创建_id字段并为其分配唯一的ObjectId value，由插入的文档验证：

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

当操作为 run 时，ObjectId值特定于机器和 time。因此，您的值可能与 example 中的值不同。

插入指定_id 字段的文档

在下面的示例中，传递给insert()方法的文档包含_id字段。 _id的 value 在集合中必须是唯一的，以避免重复的 key 错误。

db.products.insert( { _id: 10, item: "box", qty: 20 } )

该操作在products集合中插入以下文档：

{ "_id" : 10, "item" : "box", "qty" : 20 }

插入多个文档

以下 example 通过将 array 文档传递给insert()方法来执行三个文档的批量插入。默认情况下，MongoDB 执行有序的 insert。对于有序插入，如果在其中一个文档的 insert 期间发生错误，MongoDB 将返回错误而不处理 array 中的其余文档。

array 中的文档不需要具有相同的字段。例如，array 中的第一个文档有一个_id字段和一个type字段。由于第二个和第三个文档不包含_id字段，mongod将在 insert 期间为第二个和第三个文档创建_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 }

执行无序 Insert

以下 example 执行三个文档的无序插入。对于无序插入，如果在其中一个文档的 insert 期间发生错误，MongoDB 将继续插入 array 中的其余文档。

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: majority"的"w: majority"，其wtimeout为 5000 毫秒，以便该方法在写入传播到大多数表决副本集成员后返回，或者该方法在 5 秒后超时。

在 version 3.0 中更改：在以前的版本中，majority指的是副本集的大多数成员而不是大多数投票成员。

db.products.insert(
    { item: "envelopes", qty : 100, type: "Clasp" },
    { writeConcern: { w: "majority", wtimeout: 5000 } }
)

写结果

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

成功的结果

insert()返回包含操作状态的写结果 object。成功后，写结果 object 包含有关插入文档数量的信息：

WriteResult({ "nInserted" : 1 })

写关注错误

如果insert()方法遇到写入关注错误，则结果包括WriteResult.writeConcernError字段：

WriteResult({
    "nInserted" : 1,
    "writeConcernError" : {
        "code" : 64,
        "errmsg" : "waiting for replication timed out at shard-a"
    }
})

与写关注无关的错误

如果insert()方法遇到 non-write 关注错误，则结果包括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

传递 array 文档时，insert()返回BulkWriteResult() object。有关详细信息，请参阅BulkWriteResult()。

译者：李冠飞

校对：