- Reference >
mongo
Shell Methods >- Collection Methods >
- db.collection.bulkWrite()
db.collection.bulkWrite()¶
On this page
Definition¶
-
db.collection.
bulkWrite
()¶ New in version 3.2.
Performs multiple write operations with controls for order of execution.
bulkWrite()
has the following syntax:Parameter Type Description operations
array An array of
bulkWrite()
write operations.Valid operations are:
See Write Operations for usage of each operation.
writeConcern
document Optional. A document expressing the write concern. Omit to use the default write concern.
Do not explicitly set the write concern for the operation if run in a transaction. To use write concern with transactions, see Read Concern/Write Concern/Read Preference.
ordered
boolean Optional. A boolean specifying whether the
mongod
instance should perform an ordered or unordered operation execution. Defaults totrue
.Returns: - A boolean
acknowledged
astrue
if the operation ran with write concern orfalse
if write concern was disabled. - A count for each write operation.
- An array containing an
_id
for each successfully inserted or upserted documents.
- A boolean
Behavior¶
bulkWrite()
takes an array of write operations and
executes each of them. By default operations are executed in order.
See Execution of Operations for controlling
the order of write operation execution.
Write Operations¶
updateOne and updateMany¶
Changed in version 3.6: The updateOne
and updateMany
operations add support for
arrayFilters
parameter that determines which elements to modify
in an array field. Refer to db.collection.updateOne()
and
db.collection.updateMany()
for details.
Changed in version 3.4: Add support for collation. Refer to
db.collection.updateOne()
and
db.collection.updateMany()
for details
updateOne
updates a single document in the collection that matches the
filter. If multiple documents match, updateOne
will update the first
matching document only. See db.collection.updateOne()
.
updateMany
updates all documents in the collection that match the
filter. See db.collection.updateMany()
.
Use query selectors such as those used with
find()
for the filter
field.
Use Update Operators
such as $set
, $unset
, or $rename
for the update
field.
By default, upsert
is false
.
replaceOne¶
Changed in version 3.4: Add support for collation. Refer to
db.collection.replaceOne()
for details
replaceOne
replaces a single document in the collection that matches the
filter. If multiple documents match, replaceOne
will replace the first
matching document only. See db.collection.replaceOne()
.
Use query selectors such as those used with
find()
for the filter
field.
The replacement
field cannot contain
update operators.
By default, upsert
is false
.
deleteOne and deleteMany¶
Changed in version 3.4: Add support for collation. Refer to
db.collection.deleteOne()
and
db.collection.deleteMany()
for details
deleteOne
deletes a single document in the collection that match the
filter. If multiple documents match, deleteOne
will delete the first
matching document only. See db.collection.deleteOne()
.
deleteMany
deletes all documents in the collection that match the
filter. See db.collection.deleteMany()
.
Use query selectors such as those used with
find()
for the filter
field.
_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.
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.
If the document contains an _id
field, the _id
value must be
unique within the collection to avoid duplicate key error.
Update or replace operations cannot specify an _id
value that differs
from the original document.
Execution of Operations¶
The ordered
parameter specifies whether
bulkWrite()
will execute operations in order or not.
By default, operations are executed in order.
The following code represents a bulkWrite()
with
five operations.
In the default ordered : true
state, each operation will
be executed in order, from the first operation insertOne
to the last operation 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.
The following code represents an unordered
bulkWrite()
with six operations:
With ordered : false
, the results of the operation may vary. 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.
The number of operations in each group cannot exceed the value of
the maxWriteBatchSize
of
the database. As of MongoDB 3.6, this value is 100,000
.
This value is shown in the hello.maxWriteBatchSize
field.
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.
Note
The driver only divides the group into smaller groups when using the high-level API. If using db.runCommand() directly (for example, when writing a driver), MongoDB throws an error when attempting to execute a write batch which exceeds the limit.
Starting in MongoDB 3.6, once the error report for a single batch grows
too large, MongoDB truncates all remaining error messages to the empty
string. Currently, begins once there are at least 2 error messages with
total size greater than 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.
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.
replaceOne
throws a WriteError
if the
replacement
document has a larger size than the original
document.
deleteOne
and deleteMany
throw a WriteError
if used on a
capped collection.
Error Handling¶
bulkWrite()
throws a BulkWriteError
exception on
errors.
Excluding Write Concern errors, ordered operations stop after an error, while unordered operations continue to process any remaining write operations in the queue.
Write concern errors are displayed in the writeConcernErrors
field, while
all other errors are displayed in the writeErrors
field. 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.
Transactions¶
db.collection.bulkWrite()
supports multi-document transactions.
For insert and upsert: true
operations, the collection must already
exist.
Do not explicitly set the write concern for the operation if run in a transaction. To use write concern with transactions, see Read Concern/Write Concern/Read Preference.
Important
In most cases, multi-document transaction incurs a greater performance cost over single document writes, and the availability of multi-document transaction should not be a replacement for effective schema design. For many scenarios, the denormalized data model (embedded documents and arrays) will continue to be optimal for your data and use cases. That is, for many scenarios, modeling your data appropriately will minimize the need for multi-document transactions. For additional transactions usage considerations (such as runtime limit and oplog size limit), see also Production Considerations.
Examples¶
Bulk Write Operations¶
The characters
collection in the guidebook
database contains the following documents:
The following bulkWrite()
performs multiple
operations on the collection:
The operation returns the following:
If the collection had contained a document with "_id" : 5"
before executing the bulk write, then when the bulk write is executed,
the following duplicate key exception would be thrown for the second insertOne:
Since ordered
is true by default, only the first operation completes
successfully. The rest are not executed. Running the
bulkWrite()
with ordered : false
would allow the
remaining operations to complete despite the error.
Unordered Bulk Write¶
The characters
collection in the guidebook
database contains the following documents:
The following bulkWrite()
performs multiple
unordered
operations on the characters
collection. Note that one of
the insertOne
stages has a duplicate _id
value:
The operation returns the following:
Since this was an unordered
operation, the writes remaining in the queue
were processed despite the exception.
Bulk Write with Write Concern¶
The enemies
collection contains the following documents:
The following bulkWrite()
performs multiple
operations on the collection using a write concern value of
"majority"
and timeout value of 100 milliseconds:
If the total time required for all required nodes in the replica set to
acknowledge the write operation is greater than wtimeout
,
the following writeConcernError
is displayed when the wtimeout
period
has passed.
The result set shows the operations executed since
writeConcernErrors
errors are not an indicator that any write
operations failed.