mongodb/mongo-ruby-driver

***********
Bulk Writes
***********

.. default-domain:: mongodb

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

.. _bulk-operations:

The bulk write API sends several write operations to the server in a single
command. Use the bulk write API to reduce the number of network round-trips
when performing several writes at a time. For example, to efficiently perform
multiple updates, one might do:

.. code-block:: ruby

  collection = client['colors']
  collection.bulk_write([
    {
      update_one: {
        filter: {name: 'yellow'},
        update: {'$set' => {hex: 'ffff00'}},
      },
    },
    {
      update_one: {
        filter: {name: 'purple'},
        update: {'$set' => {hex: '800080'}},
      },
    },
  ], ordered: true, write_concern: {w: :majority})

The following example shows how to execute different types of operations
in the same request:

.. code-block:: ruby

  collection.bulk_write([
    { insert_one: { x: 1 } },
    { update_one: {
      filter: { x: 1 },
      update: {'$set' => { x: 2 } },
    } },
    { replace_one: {
      filter: { x: 2 },
      replacement: { x: 3 },
    } },
  ], :ordered => true)

The first argument to ``bulk_write`` is the list of operations to perform.
Each operation must be specified as a hash with exactly one key which is
the operation name and the operation specification as the corresponding
value. The supported operations are detailed below. The ``bulk_write`` method
also accepts the following options:

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

   * - Option
     - Description
   * - ``bypass_document_validation``
     - ``true`` or ``false``. Whether to bypass document validation.
   * - ``ordered``
     - If the ``ordered`` option is set to ``true`` (which is the default),
       the operations are applied in order and if any operation fails, subsequent
       operations are not attempted. If the ``ordered`` option is set to ``false``,
       all specified operations are attempted.
   * - ``write_concern``
     - The write concern for the operation, specified as a hash.

Valid bulk write operations are the following:


insert_one
==========

.. code-block:: ruby

  { insert_one: { x: 1 } }

.. note::

  There is no ``insert_many`` bulk operation. To insert multiple documents,
  specify multiple ``insert_one`` operations.


update_one
==========

.. code-block:: ruby

  { update_one: {
    filter: { x: 1 },
    update: { '$set' => { x: 2 } },
    # upsert is optional and defaults to false
    upsert: true,
  } }


update_many
===========

.. code-block:: ruby

  { update_many: {
    filter: { x: 1 },
    update: { '$set' =>  { x: 2 } },
    # upsert is optional and defaults to false
    :upsert => true,
  } }


replace_one
===========

.. code-block:: ruby

    { replace_one: {
      filter: { x: 1 },
      replacement: { x: 2 },
      # upsert is optional and defaults to false
      upsert: true,
    } }

.. note::

  The ``:replace_one`` operation requires that the replacement value is a
  document. ``:replace_one`` does not recognize MongoDB update operators in
  the replacement value. In a future release the driver is expected to
  prohibit using keys beginning with ``$`` in the replacement document.


delete_one
==========

.. code-block:: ruby

  { delete_one: {
    filter: { x: 1 },
  } }


delete_many
===========

.. code-block:: ruby

  { delete_many: {
    filter: { x: 1 },
  } }


Bulk Write Splitting
====================

The driver allows the application to submit arbitrarily large bulk write
requests. However, since MongoDB server limits the size of command documents
(currently this limit is 48 MiB), bulk writes that exceed this limit will be
split into multiple requests.

When :ref:`client-side encryption <client-side-encryption>` is used, the
threshold used for bulk write splitting is reduced to allow for overhead in
the ciphertext.