db.collection.bulkWrite（）

MongoDB 中文手册

参考 > 参考 > mongo Shell方法 > 收集方法 > db.collection.bulkWrite（）

在本页面

定义
行为
例子

定义¶

db.collection.bulkWrite（）¶

mongo 壳法

此页面记录了mongoshell方法，并且没有引用MongoDB Node.js驱动程序（或任何其他驱动程序）方法。对于相应的MongoDB驱动程序API，请改为参考您特定的 MongoDB驱动程序文档。

3.2版中的新功能。

使用控件执行多个写入操作以执行顺序。

db.collection.bulkWrite() 具有以下语法：

复制

db.collection.bulkWrite(
   [ <operation 1>, <operation 2>, ... ],
   {
      writeConcern : <document>,
      ordered : <boolean>
   }
)

参数类型描述

operations

数组

一组bulkWrite()写操作。

有效的操作是：

insertOne updateOne updateMany	deleteOne deleteMany replaceOne

有关每个操作的用法，请参见写操作。

writeConcern

文献

可选的。表达书面关切的文件。省略使用默认的写关注。

如果在事务中运行，则不要为操作明确设置写关注点。要对事务使用写关注，请参见事务和写关注。

ordered

布尔值

可选的。一个布尔值，指定mongod实例应执行有序操作还是无序操作执行。默认为true。

请参阅执行操作

返回值：	一个布尔值`acknowledged`，`true`好像该操作在运行时带有写关注关系，或者`false`禁用了写关注关系。每个写入操作的计数。一个数组，其中包含`_id`每个成功插入或升级后的文档的。

行为¶

bulkWrite()接受一组写入操作并执行每个操作。默认情况下，操作按顺序执行。见操作的执行用于控制写入操作执行的顺序。

写操作¶

insertOne ¶

将单个文档插入集合中。

复制

db.collection.bulkWrite( [
   { insertOne : { "document" : <document> } }
] )

请参阅db.collection.insertOne()。

updateOne和updateMany ¶

updateOne
updateMany

updateOne更新集合中与过滤器匹配的单个文档。如果多个文档匹配，updateOne将仅更新第一个匹配的文档。

复制

db.collection.bulkWrite( [
   { updateOne :
      {
         "filter": <document>,
         "update": <document or pipeline>,            // Changed in 4.2
         "upsert": <boolean>,
         "collation": <document>,                     // Available starting in 3.4
         "arrayFilters": [ <filterdocument1>, ... ],  // Available starting in 3.6
         "hint": <document|string>                    // Available starting in 4.2.1
      }
   }
] )

updateMany更新集合中与过滤器匹配的所有文档。

复制

db.collection.bulkWrite( [
   { updateMany :
      {
         "filter" : <document>,
         "update" : <document or pipeline>,          // Changed in MongoDB 4.2
         "upsert" : <boolean>,
         "collation": <document>,                    // Available starting in 3.4
         "arrayFilters": [ <filterdocument1>, ... ], // Available starting in 3.6
         "hint": <document|string>                   // Available starting in 4.2.1
      }
   }
] )

领域	笔记
`filter`	更新的选择标准。提供与方法中相同的查询选择器 `db.collection.find()`。
`update`	要执行的更新操作。可以指定：仅包含更新运算符表达式的文档。一个聚合管道，指定要执行的修改。`[ <stage1>, <stage2>, ... ]`
`upsert`	可选的。一个布尔值，指示是否执行upsert。默认情况下`upsert`为`false`。
`arrayFilters`	可选的。筛选器文档数组，用于确定要对数组字段进行更新操作要修改的数组元素。
`collation`	可选的。指定用于操作的排序规则。
`hint`	可选的。用于支持更新的索引`filter`。如果指定的索引不存在，则操作错误。 4.2.1版中的新功能。

有关详细信息，请参见db.collection.updateOne()和 db.collection.updateMany()。

replaceOne ¶

replaceOne替换集合中与过滤器匹配的单个文档。如果多个文档匹配，replaceOne将仅替换第一个匹配的文档。

复制

db.collection.bulkWrite([
   { replaceOne :
      {
         "filter" : <document>,
         "replacement" : <document>,
         "upsert" : <boolean>,
         "collation": <document>,                    // Available starting in 3.4
         "hint": <document|string>                   // Available starting in 4.2.1
      }
   }
] )

领域	笔记
`filter`	替换操作的选择标准。提供与方法中相同的查询选择器 `db.collection.find()`。
`replacement`	替换文件。该文档不能包含更新运算符。
`upsert`	可选的。一个布尔值，指示是否执行upsert。默认情况下`upsert`为`false`。
`collation`	可选的。指定用于操作的排序规则。
`hint`	可选的。用于支持更新的索引`filter`。如果指定的索引不存在，则操作错误。 4.2.1版中的新功能。

有关详细信息，请参见db.collection.replaceOne()。

deleteOne和deleteMany ¶

deleteOne
deleteMany

deleteOne删除集合中与过滤器匹配的单个文档。如果多个文档匹配，deleteOne将仅删除第一个匹配的文档。

复制

db.collection.bulkWrite([
   { deleteOne : {
      "filter" : <document>,
      "collation" : <document>                   // Available starting in 3.4
   } }
] )

deleteMany删除集合中与过滤器匹配的所有文档。

复制

db.collection.bulkWrite([
   { deleteMany: {
      "filter" : <document>,
      "collation" : <document>                    // Available starting in 3.4
   } }
] )

领域	笔记
`filter`	删除操作的选择标准。提供与方法中相同的查询选择器 `db.collection.find()`。
`collation`	可选的。指定用于操作的排序规则。

有关详细信息，请参见db.collection.deleteOne()和 db.collection.deleteMany()。

`_id`字段¶

如果文档未指定_id字段，则在插入或上载文档之前，请mongod 添加该_id字段并ObjectId为文档分配唯一性。大多数驱动程序会创建一个ObjectId并插入_id字段，但如果驱动程序或应用程序未mongod创建，则会创建并填充_id。

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

更新或替换操作不能指定_id与原始文档不同的值。

操作的执行¶

该ordered参数指定是否 bulkWrite()将按顺序执行操作。默认情况下，操作按顺序执行。

以下代码代表bulkWrite()具有五个操作的。

复制

db.collection.bulkWrite(
   [
      { insertOne : <document> },
      { updateOne : <document> },
      { updateMany : <document> },
      { replaceOne : <document> },
      { deleteOne : <document> },
      { deleteMany : <document> }
   ]
)

在默认状态下，每个操作将按顺序执行，从第一个操作到最后一个操作。ordered : trueinsertOnedeleteMany

如果ordered设置为false，可以对操作进行重新排序 mongod以提高性能。应用程序不应取决于操作执行的顺序。

以下代码表示一个无序 bulkWrite()的六个操作：

复制

db.collection.bulkWrite(
   [
      { insertOne : <document> },
      { updateOne : <document> },
      { updateMany : <document> },
      { replaceOne : <document> },
      { deleteOne : <document> },
      { deleteMany : <document> }
   ],
   { ordered : false }
)

使用，操作结果可能会有所不同。例如，或者可能因去除更多或更少的文件，无论是前或后运行，，，或操作。ordered : falsedeleteOnedeleteManyinsertOneupdateOneupdateManyreplaceOne

每个组中的操作数不能超过maxWriteBatchSize数据库的值。从MongoDB 3.6开始，此值为100,000。该值显示在该isMaster.maxWriteBatchSize字段中。

此限制可防止出现错误消息过多的问题。如果某个组超过了此数量limit，则客户端驱动程序会将其分为计数小于或等于限制值的较小组。例如，如果maxWriteBatchSize值为100,000，则如果队列包含 200,000操作，则驱动程序将创建2个组，每个组均包含 100,000操作。

注意

当使用高级API时，驱动程序仅将组划分为较小的组。如果直接使用 db.runCommand（）（例如，在编写驱动程序时），则MongoDB在尝试执行超出限制的写批处理时会引发错误。

从MongoDB 3.6开始，一旦单个批次的错误报告变得太大，MongoDB就会将所有剩余的错误消息截断为空字符串。当前，一旦至少有2条错误消息且总大小大于，便开始1MB。

大小和分组机制是内部性能的详细信息，将来可能会更改。

ordered在分片集合上执行操作列表通常比执行unordered列表要慢，因为对于有序列表，每个操作必须等待上一个操作完成。

封顶集合¶

bulkWrite()写操作在有限制的集合上使用时有限制。

updateOne和updateMany抛出WriteError如果 update标准增加被修改文档的大小。

replaceOneWriteError如果replacement文档的大小大于原始文档的大小，则抛出。

deleteOne并deleteMany抛出一个WriteError如果上加盖收集使用。

错误处理¶

db.collection.bulkWrite()抛出BulkWriteError 错误异常（除非该操作是MongoDB 4.0上的事务的一部分）。请参阅事务内部的错误处理。

排除Write Concern错误后，有序操作将在发生错误后停止，而无序操作将继续处理队列中所有剩余的写操作，除非在事务内部运行。请参阅事务内部的错误处理。

写关注错误显示在该writeConcernErrors字段中，而所有其他错误显示在该writeErrors字段中。如果遇到错误，将显示成功写入操作的次数，而不是插入的_id值。有序操作显示遇到的单个错误，而无序操作显示数组中的每个错误。

交易¶

db.collection.bulkWrite()可以在多文档交易中使用。

如果在事务内运行，则该集合必须已经存在才能进行插入和操作。upsert: true

如果在事务中运行，则不要为操作明确设置写关注点。要对事务使用写关注，请参见事务和写关注。

重要

在大多数情况下，与单文档写入相比，多文档事务产生的性能成本更高，并且多文档事务的可用性不应代替有效的架构设计。在许多情况下，非规范化数据模型（嵌入式文档和数组）对于您的数据和用例将继续是最佳的。也就是说，在许多情况下，对数据进行适当的建模将最大程度地减少对多文档交易的需求。

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

里面的错误处理事务¶

从MongoDB 4.2开始，如果db.collection.bulkWrite() 操作在事务内部遇到错误，则该方法将引发BulkWriteException（与事务外部相同）。

在4.0中，如果bulkWrite操作在事务内部遇到错误，则抛出的错误不会包装为 BulkWriteException。

在事务内部，即使批量写入是无序的，批量写入中的第一个错误也会导致整个批量写入失败并中止事务。

例子¶

批量写操作¶

将characters在收集guidebook数据库包含以下文件：

复制

{ "_id" : 1, "char" : "Brisbane", "class" : "monk", "lvl" : 4 },
{ "_id" : 2, "char" : "Eldon", "class" : "alchemist", "lvl" : 3 },
{ "_id" : 3, "char" : "Meldane", "class" : "ranger", "lvl" : 3 }

以下bulkWrite()对集合执行多项操作：

复制

try {
   db.characters.bulkWrite([
      { insertOne: { "document": { "_id": 4, "char": "Dithras", "class": "barbarian", "lvl": 4 } } },
      { insertOne: { "document": { "_id": 5, "char": "Taeln", "class": "fighter", "lvl": 3 } } },
      { updateOne : {
         "filter" : { "char" : "Eldon" },
         "update" : { $set : { "status" : "Critical Injury" } }
      } },
      { deleteOne : { "filter" : { "char" : "Brisbane"} } },
      { replaceOne : {
         "filter" : { "char" : "Meldane" },
         "replacement" : { "char" : "Tanys", "class" : "oracle", "lvl": 4 }
      } }
   ]);
} catch (e) {
   print(e);
}

该操作返回以下内容：

复制

{
   "acknowledged" : true,
   "deletedCount" : 1,
   "insertedCount" : 2,
   "matchedCount" : 2,
   "upsertedCount" : 0,
   "insertedIds" : {
      "0" : 4,
      "1" : 5
   },
   "upsertedIds" : {

   }
}

如果在执行批量写入之前该集合包含一个文档，则在执行批量写入时，将为第二个insertOne抛出以下重复键异常："_id" : 5"

复制

BulkWriteError({
   "writeErrors" : [
      {
         "index" : 1,
         "code" : 11000,
         "errmsg" : "E11000 duplicate key error collection: guidebook.characters index: _id_ dup key: { _id: 5.0 }",
         "op" : {
            "_id" : 5,
            "char" : "Taeln",
            "class" : "fighter",
            "lvl" : 3
         }
      }
   ],
   "writeConcernErrors" : [ ],
   "nInserted" : 1,
   "nUpserted" : 0,
   "nMatched" : 0,
   "nModified" : 0,
   "nRemoved" : 0,
   "upserted" : [ ]
})

由于ordered默认情况下为true，因此仅第一个操作成功完成。其余的不执行。运行 bulkWrite()with 将允许其余操作完成，尽管出现错误。ordered : false

无序大写¶

将characters在收集guidebook数据库包含以下文件：

复制

{ "_id" : 1, "char" : "Brisbane", "class" : "monk", "lvl" : 4 },
{ "_id" : 2, "char" : "Eldon", "class" : "alchemist", "lvl" : 3 },
{ "_id" : 3, "char" : "Meldane", "class" : "ranger", "lvl" : 3 }

以下对集合bulkWrite()执行多项 unordered操作characters。请注意，其中一个insertOne阶段具有重复_id值：

复制

MongoDB 中文手册

db.collection.bulkWrite（）

定义¶

行为¶

写操作¶

insertOne ¶

updateOne和updateMany ¶

replaceOne ¶

deleteOne和deleteMany ¶

_id字段¶

操作的执行¶

封顶集合¶

错误处理¶

交易¶

里面的错误处理事务¶

例子¶

批量写操作¶

无序大写¶

`_id`字段¶