db.collection.bulkWrite() (mongosh method方法)

Write Operations写入操作

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

db.collection.bulkWrite( [
   { updateOne :
      {
         "filter": <document>,
         "update": <document or pipeline>,
         "upsert": <boolean>,
         "collation": <document>,
         "arrayFilters": [ <filterdocument1>, ... ],
         "hint": <document|string>
      }
   }
] )

db.collection.bulkWrite( [
   { updateMany :
      {
         "filter" : <document>,
         "update" : <document or pipeline>,
         "upsert" : <boolean>,
         "collation": <document>,
         "arrayFilters": [ <filterdocument1>, ... ],
         "hint": <document|string>
      }
   }
] )

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

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将创建并填充该_id。

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.在默认的order:true状态下，每个操作都将按顺序执行，从第一个操作insertOne到最后一个操作deleteMany。

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

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个操作，驱动程序将创建2个组，每个组包含100000个操作。

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

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.在分片集合上执行ordered（有序）操作列表通常比执行unordered（无序）列表慢，因为使用有序列表，每个操作都必须等待前一个操作完成。

Capped Collections封顶集合

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

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。

Error Handling错误处理

db.collection.bulkWrite() throws a BulkWriteError exception on errors. 在出现错误时抛出BulkWriteError异常。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. Ordered operations display the single error encountered while unordered operations display each error in an array.如果遇到错误，将显示成功写入操作的次数，而不是插入的_id值。有序操作显示遇到的单个错误，而无序操作显示数组中的每个错误。

Transactions事务

db.collection.bulkWrite() can be used inside distributed transactions.db.collection.bulkWrite()可以在分布式事务中使用。

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 db.collection.bulkWrite() example runs the following operations on the pizzas collection:以下db.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.要完成所有没有错误的操作，请在有序设置为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操作的_id与第一个insertOne相同，这会导致重复键错误。

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. In an unordered bulkWrite(), any operation without an error is completed.由于重复键错误，第二次insertOne操作失败。在无序bulkWrite()中，任何没有错误的操作都会完成。

Write Concern Errors in Sharded Clusters分片集群中的写入关注错误

When db.collection.bulkWrite() executes on mongos in a sharded cluster, a writeConcernError is always reported in the response, even when one or more other errors occur. 当db.collection.bulkWrite()在分片集群中的mongos上执行时，即使出现一个或多个其他错误，也总是在响应中报告writeConcernError。In previous releases, other errors sometimes caused db.collection.bulkWrite() to not report write concern errors.在以前的版本中，其他错误有时会导致db.collection.bulkWrite()不报告写入关注错误。

For example, if a document fails validation, triggering a DocumentValidationFailed error, and a write concern error also occurs, both the DocumentValidationFailed error and the writeConcernError are returned in the top-level field of the response.例如，如果文档验证失败，触发DocumentValidationFailed错误，并且还发生写入关注错误，则DocumentValidationFailure错误和writeConcernError都会在响应的顶级字段中返回。

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: 'WriteConcernTimeout',
               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") }
   }
}