db.collection.bulkWrite()

Write Operations写入操作

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

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
      }
   }
] )

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
      }
   }
] )

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
      }
   }
] )

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

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

_id Field字段

If the document does not specify an _id field, then mongod adds the _id field and assign a unique ObjectId() for the document before inserting or upserting it. 如果文档没有指定_id字段，那么mongod会添加_id字段并在插入或追加文档之前为文档分配一个唯一的ObjectId()。Most drivers create an ObjectId and insert the _id field, but the mongod will create and populate the _id if the driver or application does not.大多数驱动程序创建一个ObjectId并插入_id字段，但如果驱动程序或应用程序没有创建并填充_id，mongod将创建并填充。

If the document contains an _id field, the _id value must be unique within the collection to avoid duplicate key error.如果文档包含_id字段，则_id值在集合中必须是唯一的，以避免重复的键错误。

Update or replace operations cannot specify an _id value that differs from the original document.更新或替换操作不能指定与原始文档不同的_id值。

Execution of Operations操作的执行

The ordered parameter specifies whether bulkWrite() will execute operations in order or not. By default, operations are executed in order.ordered参数指定bulkWrite()是否按顺序执行操作。默认情况下，操作按顺序执行。

The following code represents a bulkWrite() with five operations.以下代码表示一个包含五个操作的bulkWrite()。

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

In the default ordered : true state, each operation will be executed in order, from the first operation insertOne to the last operation deleteMany.在默认的orderd:true状态下，每个操作都将按顺序执行，从第一个操作insertOne到最后一个操作deleteMany。

If ordered is set to false, operations may be reordered by mongod to increase performance. 如果ordered设置为false，mongod可以重新排序操作以提高性能。Applications should not depend on order of operation execution.应用程序不应依赖于操作执行的顺序。

The following code represents an unordered bulkWrite() with six operations:以下代码表示一个包含六个操作的无序bulkWrite()：

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

With ordered : false, the results of the operation may vary. 使用ordered : false时，操作的结果可能会有所不同。For example, the deleteOne or deleteMany may remove more or fewer documents depending on whether the run before or after the insertOne, updateOne, updateMany, or replaceOne operations.例如，deleteOne或deleteMany可能会删除更多或更少的文档，具体取决于在insertOne、updateOne、updateMany或replaceOne操作之前还是之后运行。

The number of operations in each group cannot exceed the value of the maxWriteBatchSize of the database. 每个组中的操作数不能超过数据库的maxWriteBatchSize值。The default value of maxWriteBatchSize is 100,000. maxWriteBatchSize的默认值为100000。This value is shown in the hello.maxWriteBatchSize field.该值显示在hello.maxWriteBatchSize字段中。

This limit prevents issues with oversized error messages. 此限制可防止出现错误消息过大的问题。If a group exceeds this limit, the client driver divides the group into smaller groups with counts less than or equal to the value of the limit. 如果一个组超过此限制，客户端驱动程序会将该组划分为计数小于或等于限制值的较小组。For example, with the maxWriteBatchSize value of 100,000, if the queue consists of 200,000 operations, the driver creates 2 groups, each with 100,000 operations.例如，当maxWriteBatchSize值为100000时，如果队列由200000个操作组成，则驱动程序将创建两个组，每个组包含100000个操作。

If the error report for a single batch grows too large, MongoDB truncates all remaining error messages to the empty string. 如果单个批次的错误报告过大，MongoDB会将所有剩余的错误消息截断为空字符串。If there are at least two error messages with total size greater than 1MB, they are trucated.如果至少有两条错误消息的总大小大于1MB，则对它们进行trucated。

The sizes and grouping mechanics are internal performance details and are subject to change in future versions.尺寸和分组机制是内部性能细节，在未来版本中可能会发生变化。

Executing an ordered list of operations on a sharded collection will generally be slower than executing an unordered list since with an ordered list, each operation must wait for the previous operation to finish.在分片集合上执行有序操作列表通常比执行无序列表慢，因为对于有序列表，每个操作都必须等待上一个操作完成。

Capped Collections封顶集合

bulkWrite() write operations have restrictions when used on a capped collection.bulkWrite()写操作在封顶集合上使用时有限制。

updateOne and updateMany throw a WriteError if the update criteria increases the size of the document being modified.如果update条件增加了要修改的文档的大小，updateOne和updateMany将抛出WriteError。

replaceOne throws a WriteError if the replacement document has a larger size than the original document.如果replacement文档的大小大于原始文档的大小，replaceOne将抛出WriteError。

deleteOne and deleteMany throw a WriteError if used on a capped collection.如果deleteOne和deleteMany用于封顶集合，则抛出WriteError。

Time Series Collections时间序列集合

bulkWrite() write operations have restrictions when used on a time series collection. 写入操作在时间序列集合上使用时有限制。Only insertOne can be used on time series collections. All other operations will return a WriteError.只有insertOne可以用于时间序列集合。所有其他操作都将返回WriteError。

Error Handling错误处理

db.collection.bulkWrite() throws a BulkWriteError exception on errors (unless the operation is part of a transaction on MongoDB 4.0). 在出现错误时抛出BulkWriteError异常（除非该操作是MongoDB 4.0上事务的一部分）。See Error Handling inside Transactions.请参阅事务内部的错误处理。

Excluding write concern errors, ordered operations stop after an error, while unordered operations continue to process any remaining write operations in the queue, unless when run inside a transaction. See Error Handling inside Transactions.除了写入关注错误，有序操作在错误后停止，而无序操作继续处理队列中的任何剩余写操作，除非在事务内部运行。请参阅事务内部的错误处理。

Write concern errors are displayed in the writeConcernErrors field, while all other errors are displayed in the writeErrors field. 写入关注错误显示在writeConcernErrors字段中，而所有其他错误都显示在writeErrors字段。If an error is encountered, the number of successful write operations are displayed instead of the inserted _id values. 如果遇到错误，则显示成功写入操作的次数，而不是插入的_id值。Ordered operations display the single error encountered while unordered operations display each error in an array.有序操作显示遇到的单个错误，而无序操作显示数组中的每个错误。

Transactions事务

db.collection.bulkWrite() can be used inside multi-document transactions.可以在多文档事务中使用。

Ordered Bulk Write Example有序大容量写入示例

It is important that you understand bulkWrite() operation ordering and error handling. By default, bulkWrite() runs an ordered list of operations:了解bulkWrite()操作顺序和错误处理非常重要。默认情况下，bulkWrite()运行一个有序的操作列表：

• Operations run serially.操作以串行方式运行。
• If an operation has an error, that operation and any following operations are not run.如果某个操作出现错误，则不会运行该操作和任何后续操作。
• Operations listed before the error operation are completed.错误操作完成之前列出的操作。

The bulkWrite() examples use the pizzas collection:bulkWrite()示例使用pizzas集合：

db.pizzas.insertMany( [
   { _id: 0, type: "pepperoni", size: "small", price: 4 },
   { _id: 1, type: "cheese", size: "medium", price: 7 },
   { _id: 2, type: "vegan", size: "large", price: 8 }
] )

The following bulkWrite() example runs these operations on the pizzas collection:下面的bulkWrite()示例对pizzas集合运行这些操作：

• Adds two documents using insertOne.使用insertOne添加两个文档。
• Updates a document using updateOne.使用updateOne更新文档。
• Deletes a document using deleteOne.使用deleteOne删除文档。
• Replaces a document using replaceOne.使用replaceOne替换文档。

try {
   db.pizzas.bulkWrite( [
      { insertOne: { document: { _id: 3, type: "beef", size: "medium", price: 6 } } },
      { insertOne: { document: { _id: 4, type: "sausage", size: "large", price: 10 } } },
      { updateOne: {
         filter: { type: "cheese" },
         update: { $set: { price: 8 } }
      } },
      { deleteOne: { filter: { type: "pepperoni"} } },
      { replaceOne: {
         filter: { type: "vegan" },
         replacement: { type: "tofu", size: "small", price: 4 }
      } }
   ] )
} catch( error ) {
   print( error )
}

Example output, which includes a summary of the completed operations:示例输出，其中包括已完成操作的摘要：

{
   acknowledged: true,
   insertedCount: 2,
   insertedIds: { '0': 3, '1': 4 },
   matchedCount: 2,
   modifiedCount: 2,
   deletedCount: 1,
   upsertedCount: 0,
   upsertedIds: {}
}

If the collection already contained a document with an _id of 4 before running the previous bulkWrite() example, the following duplicate key exception is returned for the second insertOne operation:如果在运行上一个bulkWrite()示例之前，集合已包含一个_id为4的文档，则第二个insertOne操作将返回以下重复键异常：

writeErrors: [
   WriteError {
      err: {
         index: 1,
         code: 11000,
         errmsg: 'E11000 duplicate key error collection: test.pizzas index: _id_ dup key: { _id: 4 }',
         op: { _id: 4, type: 'sausage', size: 'large', price: 10 }
      }
   }
],
result: BulkWriteResult {
   result: {
      ok: 1,
      writeErrors: [
         WriteError {
            err: {
               index: 1,
               code: 11000,
               errmsg: 'E11000 duplicate key error collection: test.pizzas index: _id_ dup key: { _id: 4 }',
               op: { _id: 4, type: 'sausage', size: 'large', price: 10 }
            }
         }
      ],
      writeConcernErrors: [],
      insertedIds: [ { index: 0, _id: 3 }, { index: 1, _id: 4 } ],
      nInserted: 1,
      nUpserted: 0,
      nMatched: 0,
      nModified: 0,
      nRemoved: 0,
      upserted: []
   }
}

Because the bulkWrite() example is ordered, only the first insertOne operation is completed.因为bulkWrite()示例是有序的，所以只完成了第一个insertOne操作。

To complete all operations that do not have errors, run bulkWrite() with ordered set to false. For an example, see the following section.若要完成所有没有错误的操作，请在ordered设置为false的情况下运行bulkWrite()。有关示例，请参阅以下部分。

Unordered Bulk Write Example无序大容量写入示例

To specify an unordered bulkWrite(), set ordered to false.若要指定无序的bulkWrite()，请将ordered设置为false。

In an unordered bulkWrite() list of operations:在无序的bulkWrite()操作列表中：

• Operations can run in parallel (not guaranteed). 操作可以并行运行（不保证）。For details. See Ordered vs Unordered Operations.请参阅有序操作与无序操作以了解详细信息。
• Operations with errors are not completed.有错误的操作未完成。
• All operations without errors are completed.所有没有错误的操作都已完成。

Continuing the pizzas collection example, drop and recreate the collection:继续pizzas集合示例，放下并重新创建该系列：

db.pizzas.insertMany( [
   { _id: 0, type: "pepperoni", size: "small", price: 4 },
   { _id: 1, type: "cheese", size: "medium", price: 7 },
   { _id: 2, type: "vegan", size: "large", price: 8 }
] )

In the following example:在以下示例中：

• bulkWrite() runs unordered operations on the pizzas collection.对pizzas集合执行无序操作。
• The second insertOne operation has the same _id as the first insertOne, which causes a duplicate key error.第二个insertOne操作具有与第一个insertOne相同的_id，这会导致重复键错误。

try {
   db.pizzas.bulkWrite( [
      { insertOne: { document: { _id: 3, type: "beef", size: "medium", price: 6 } } },
      { insertOne: { document: { _id: 3, type: "sausage", size: "large", price: 10 } } },
      { updateOne: {
         filter: { type: "cheese" },
         update: { $set: { price: 8 } }
      } },
      { deleteOne: { filter: { type: "pepperoni"} } },
      { replaceOne: {
         filter: { type: "vegan" },
         replacement: { type: "tofu", size: "small", price: 4 }
      } }
   ],
   { ordered: false } )
} catch( error ) {
   print( error )
}

Example output, which includes the duplicate key error and a summary of the completed operations:输出示例，其中包括重复键错误和已完成操作的摘要：

writeErrors: [
   WriteError {
      err: {
         index: 1,
         code: 11000,
         errmsg: 'E11000 duplicate key error collection: test.pizzas index: _id_ dup key: { _id: 3 }',
         op: { _id: 3, type: 'sausage', size: 'large', price: 10 }
      }
   }
],
result: BulkWriteResult {
   result: {
      ok: 1,
      writeErrors: [
         WriteError {
            err: {
               index: 1,
               code: 11000,
               errmsg: 'E11000 duplicate key error collection: test.pizzas index: _id_ dup key: { _id: 3 }',
               op: { _id: 3, type: 'sausage', size: 'large', price: 10 }
            }
         }
      ],
      writeConcernErrors: [],
      insertedIds: [ { index: 0, _id: 3 }, { index: 1, _id: 3 } ],
      nInserted: 1,
      nUpserted: 0,
      nMatched: 2,
      nModified: 2,
      nRemoved: 1,
      upserted: []
   }
}

The second insertOne operation fails because of the duplicate key error. 由于重复键错误，第二个insertOne操作失败。In an unordered bulkWrite(), any operation without an error is completed.在无序的bulkWrite()中，任何没有错误的操作都将完成。

Bulk Write with Write Concern Example带写入关注的大容量写入示例

Continuing the pizzas collection example, drop and recreate the collection:继续pizzas系列示例，放下并重新创建该系列：

db.pizzas.insertMany( [
   { _id: 0, type: "pepperoni", size: "small", price: 4 },
   { _id: 1, type: "cheese", size: "medium", price: 7 },
   { _id: 2, type: "vegan", size: "large", price: 8 }
] )

The following bulkWrite() example runs operations on the pizzas collection and sets a "majority" write concern with a 100 millisecond timeout:下面的bulkWrite()示例对pizzas集合运行操作，并设置一个"majority"写入关注，超时时间为100毫秒：

try {
   db.pizzas.bulkWrite( [
      { updateMany: {
         filter: { size: "medium" },
         update: { $inc: { price: 0.1 } }
      } },
      { updateMany: {
         filter: { size: "small" },
         update: { $inc: { price: -0.25 } }
      } },
      { deleteMany: { filter: { size: "large" } } },
      { insertOne: {
         document: { _id: 4, type: "sausage", size: "small", price: 12 }
      } } ],
      { writeConcern: { w: "majority", wtimeout: 100 } }
   )
} catch( error ) {
   print( error )
}

If the time for the majority of replica set members to acknowledge the operations exceeds wtimeout, the example returns a write concern error and a summary of completed operations:如果大多数副本集成员确认操作的时间超过wtimeout，则此示例将返回一个写入关注错误和已完成操作的摘要：

result: BulkWriteResult {
   result: {
      ok: 1,
      writeErrors: [],
      writeConcernErrors: [
         WriteConcernError {
            err: {
               code: 64,
               codeName: 'WriteConcernFailed',
               errmsg: 'waiting for replication timed out',
               errInfo: { wtimeout: true, writeConcern: [Object] }
            }
         }
      ],
      insertedIds: [ { index: 3, _id: 4 } ],
      nInserted: 0,
      nUpserted: 0,
      nMatched: 2,
      nModified: 2,
      nRemoved: 0,
      upserted: [],
      opTime: { ts: Timestamp({ t: 1660329086, i: 2 }), t: Long("1") }
   }
}