db.collection.bulkWrite.txt

=========================
db.collection.bulkWrite()
=========================

.. default-domain:: mongodb

.. meta::
   :description: Perform a series of ordered or unordered write operations.

.. facet::
   :name: programming_language 
   :values: shell

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

.. include:: /includes/wayfinding/mongosh-method-bulkWrite.rst

Definition
----------

.. method:: db.collection.bulkWrite()

   Performs multiple write operations with controls for order of
   execution.

   :returns:
      - A boolean ``acknowledged`` as ``true`` if the operation ran with
        :term:`write concern` or ``false`` if write concern was disabled.
      - A count for each write operation.
      - An array containing an ``_id`` for each successfully inserted or
        upserted documents.

Compatibility
-------------

.. |operator-method| replace:: ``db.collection.bulkWrite()``

|operator-method| is available in deployments hosted in the following environments:

.. include:: /includes/fact-environments-atlas-only.rst

.. include:: /includes/fact-environments-atlas-support-all.rst

.. include:: /includes/fact-environments-onprem-only.rst

.. note::

   You can't perform :ref:`bulk write <bulk-write-operations>` 
   operations in the :ref:`Atlas UI <atlas-ui-docs>`. 
   To insert multiple documents, you must insert an array of documents.
   To learn more, see :ref:`atlas-ui-docs` in the Atlas documentation. 

Syntax
------

The :method:`~db.collection.bulkWrite()` method has the following form:

.. code-block:: javascript

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

The :method:`~db.collection.bulkWrite()` method takes the following
parameters:

.. list-table::
   :header-rows: 1
   :widths: 20 20 80

   * - Parameter
     - Type
     - Description

   * - ``operations``
     - array
     - An array of :method:`~db.collection.bulkWrite()` write
       operations.

       Valid operations are:

       .. hlist::
          :columns: 2

          - :ref:`insertOne <bulkwrite-write-operations-insertOne>`
          - :ref:`updateOne <bulkwrite-write-operations-updateOneMany>`
          - :ref:`updateMany <bulkwrite-write-operations-updateOneMany>`
          - :ref:`deleteOne <bulkwrite-write-operations-deleteOneMany>`
          - :ref:`deleteMany <bulkwrite-write-operations-deleteOneMany>`
          - :ref:`replaceOne <bulkwrite-write-operations-replaceOne>`

       See :ref:`bulkwrite-write-operations` for usage of each operation

   * - ``writeConcern``
     - document
     - Optional. A document expressing the :ref:`write concern
       <write-concern>`. Omit to use the default write concern.
 
       .. include:: /includes/extracts/transactions-operations-write-concern.rst

   * - ``ordered``
     - boolean
     - Optional. A boolean specifying whether the :binary:`~bin.mongod` instance should perform
       an ordered or unordered operation execution. Defaults to ``true``.

       See :ref:`bulkwrite-write-operations-executionofoperations`

Behavior
--------

:method:`~db.collection.bulkWrite()` takes an array of write operations and
executes each of them. By default operations are executed in order.
See :ref:`bulkwrite-write-operations-executionofoperations` for controlling
the order of write operation execution.


.. _bulkwrite-write-operations:

Write Operations
~~~~~~~~~~~~~~~~

.. _bulkwrite-write-operations-insertOne:

insertOne
+++++++++

Inserts a single document into the collection.

.. code-block:: javascript

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

See :method:`db.collection.insertOne()`.

.. _bulkwrite-write-operations-updateOneMany:

updateOne and updateMany
++++++++++++++++++++++++

.. tabs::

   tabs:

      - id: updateOne
        name: updateOne
        content: |

           ``updateOne`` updates a *single* document in the collection that matches the
           filter. If multiple documents match, ``updateOne`` will update the *first*
           matching document only.

           .. code-block:: javascript

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

      - id: updateMany
        name: updateMany
        content: |

           ``updateMany`` updates *all* documents in the collection
           that match the filter.

           .. code-block:: javascript

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

.. list-table::
   :widths: 15 85
   :header-rows: 1

   * - Field
     - Notes

   * - ``filter``

     - The selection criteria for the update. The same :ref:`query
       selectors <query-selectors>` as in the
       :method:`db.collection.find()` method are available.

   * - ``update``

     - The update operation to perform. Can specify either:

       - A document that only contains :ref:`update operator
         <update-operators>` expressions.

       - An :ref:`aggregation pipeline <aggregation-pipeline>` ``[
         <stage1>, <stage2>, ... ]`` that specifies the modifications to
         perform.

   * - ``upsert``

     - Optional. A boolean to indicate whether to perform an upsert.

       By default, ``upsert`` is ``false``.

   * - ``arrayFilters``

     - Optional. An array of filter documents that determine which
       array elements to modify for an update operation on an array
       field.

   * - ``collation``

     - Optional. Specifies the :ref:`collation <collation>` to use for
       the operation.

   * - ``hint``

     - Optional. The :ref:`index <indexes>` to use to support the
       update ``filter``. If you specify an index that does not exist,
       the operation errors.


For details, see :method:`db.collection.updateOne()` and
:method:`db.collection.updateMany()`.

.. _bulkwrite-write-operations-replaceOne:

replaceOne
++++++++++

``replaceOne`` replaces a *single* document in the collection that matches the
filter. If multiple documents match, ``replaceOne`` will replace the *first*
matching document only.

.. code-block:: javascript

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

.. list-table::
   :widths: 15 85
   :header-rows: 1

   * - Field
     - Notes

   * - ``filter``

     - The selection criteria for the replacement operation. The same
       :ref:`query selectors <query-selectors>` as in the
       :method:`db.collection.find()` method are available.

   * - ``replacement``

     - The replacement document. The document cannot contain
       :ref:`update operators <update-operators>`.

   * - ``upsert``

     - Optional. A boolean to indicate whether to perform an upsert. By
       default, ``upsert`` is ``false``.

   * - ``collation``

     - Optional. Specifies the :ref:`collation <collation>` to use for
       the operation.

   * - ``hint``

     - Optional. The :ref:`index <indexes>` to use to support the
       update ``filter``. If you specify an index that does not exist,
       the operation errors.

For details, see to :method:`db.collection.replaceOne()`.

.. _bulkwrite-write-operations-deleteOneMany:

deleteOne and deleteMany
++++++++++++++++++++++++

.. tabs::

   tabs:

      - id: deleteOne
        name: deleteOne
        content: |

           ``deleteOne`` deletes a *single* document in the collection that match the
           filter. If multiple documents match, ``deleteOne`` will delete the *first*
           matching document only.

           .. code-block:: javascript

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

      - id: deleteMany
        name: deleteMany
        content: |

           ``deleteMany`` deletes *all* documents in the collection
           that match the filter.

           .. code-block:: javascript

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

.. list-table::
   :widths: 15 85
   :header-rows: 1

   * - Field
     - Notes

   * - ``filter``

     - The selection criteria for the delete operation. The same
       :ref:`query selectors <query-selectors>` as in the
       :method:`db.collection.find()` method are available.

   * - ``collation``

     - Optional. Specifies the :ref:`collation <collation>` to use for
       the operation.


For details, see :method:`db.collection.deleteOne()` and
:method:`db.collection.deleteMany()`.

.. _bulkwrite-write-operations-id:


``_id`` Field
~~~~~~~~~~~~~

If the document does not specify an :term:`_id` field, then :binary:`~bin.mongod`
adds the ``_id`` field and assign a unique
:method:`ObjectId` for the document before inserting or upserting it.
Most drivers create an ObjectId and insert the ``_id`` field, but the
:binary:`~bin.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.

.. _bulkwrite-write-operations-executionofoperations:

Execution of Operations
~~~~~~~~~~~~~~~~~~~~~~~

The ``ordered`` parameter specifies whether
:method:`~db.collection.bulkWrite()` will execute operations in order or not.
By default, operations are executed in order.

The following code represents a :method:`~db.collection.bulkWrite()` with
five operations.

.. code-block:: javascript

   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``.

If ``ordered`` is set to false, operations may be reordered by
:binary:`~bin.mongod` to increase performance.
Applications should not depend on order of operation execution.

The following code represents an unordered
:method:`~db.collection.bulkWrite()` with six operations:

.. code-block:: javascript

   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. 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.

.. include:: /includes/fact-bulkwrite-operation-batches.rst

.. include:: /includes/fact-bulk-operation-sharded-cluster.rst

Capped Collections
~~~~~~~~~~~~~~~~~~

:method:`~db.collection.bulkWrite()` write operations have restrictions when
used on a :term:`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.

.. |operation| replace:: :method:`db.collection.bulkWrite()`

Time Series Collections
~~~~~~~~~~~~~~~~~~~~~~~

:method:`~db.collection.bulkWrite()` write operations have restrictions
when used on a :term:`time series collection`. Only ``insertOne`` can be
used on time series collections. All other operations will return a
``WriteError``.

.. _bulkWrite-error-handling:

Error Handling
~~~~~~~~~~~~~~

:method:`db.collection.bulkWrite()` throws a ``BulkWriteError``
exception on errors. See :ref:`bulkwrite-error-handling-txn`.

Excluding :ref:`write concern <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 :ref:`bulkwrite-error-handling-txn`.

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.

Schema Validation Errors
++++++++++++++++++++++++

If your collection uses :ref:`schema validation
<schema-validation-overview>` and has ``validationAction`` set to 
``error``, inserting an invalid document or updating a document with
invalid values throws an error. Operations preceding the invalid 
operation in the ``operations`` array are executed and written to the 
collection. The ``ordered`` field determines if the remaining 
operations are executed.

Transactions
~~~~~~~~~~~~

.. include:: /includes/extracts/transactions-supported-operation.rst

.. include:: /includes/extracts/transactions-usage.rst

Inserts and Upserts within Transactions
+++++++++++++++++++++++++++++++++++++++

.. include:: /includes/extracts/4.4-changes-transactions-bulkWrite.rst

Write Concerns and Transactions
+++++++++++++++++++++++++++++++

.. include:: /includes/extracts/transactions-operations-write-concern.rst

.. _bulkwrite-error-handling-txn:

Error Handling inside Transactions
++++++++++++++++++++++++++++++++++

.. include:: /includes/extracts/4.2-changes-bulkWrite-txn-error-handling.rst

Examples
--------

.. _bulkwrite-example-bulk-write-operation:

Ordered Bulk Write Example
~~~~~~~~~~~~~~~~~~~~~~~~~~

It is important that you understand :method:`~db.collection.bulkWrite()`
operation ordering and error handling. By default,
:method:`~db.collection.bulkWrite()` runs an ordered list of operations:

- 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 :method:`~db.collection.bulkWrite()` examples use the ``pizzas``
collection:

.. include:: /includes/pizza-example-collection.rst

.. include:: /includes/pizza-bulk-write-example.rst

If the collection already contained a document with an ``_id`` of ``4``
before running the previous :method:`~db.collection.bulkWrite()`
example, the following duplicate key exception is returned for the
second ``insertOne`` operation:

.. code-block:: javascript
   :copyable: false

   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 :method:`~db.collection.bulkWrite()` example is ordered,
only the first ``insertOne`` operation is completed.

To complete all operations that do not have errors, run
:method:`~db.collection.bulkWrite()` with ``ordered`` set to ``false``.
For an example, see the following section.

.. _bulkwrite-example-unordered-bulk-write:

Unordered Bulk Write Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To specify an unordered :method:`~db.collection.bulkWrite()`, set
``ordered`` to ``false``.

In an unordered :method:`~db.collection.bulkWrite()` list of operations:

- Operations can run in parallel (not guaranteed). For details. See
  :ref:`bulk-write-operations-ordered-vs-unordered`.
- Operations with errors are not completed.
- All operations without errors are completed.

Continuing the ``pizzas`` collection example, drop and recreate the
collection:

.. include:: /includes/pizza-example-collection.rst

In the following example:

- :method:`~db.collection.bulkWrite()` runs unordered operations on
  the ``pizzas`` collection.
- The second ``insertOne`` operation has the same ``_id`` as the first
  ``insertOne``, which causes a duplicate key error.

.. code-block:: javascript

   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:

.. code-block:: javascript
   :copyable: false

   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 :method:`~db.collection.bulkWrite()`, any
operation without an error is completed.

.. _bulkwrite-example-bulk-write-with-write-concern:

Bulk Write with Write Concern Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Continuing the ``pizzas`` collection example, drop and recreate the
collection:

.. include:: /includes/pizza-example-collection.rst

The following :method:`~db.collection.bulkWrite()` example runs
operations on the ``pizzas`` collection and sets a ``"majority"``
:ref:`write concern <wc-w>` with a 100 millisecond :ref:`timeout
<wc-wtimeout>`:

.. code-block:: javascript

   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:

.. code-block:: javascript
   :copyable: false

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