DOCSP-41971: Bulk write

Author: norareidy

source/write/bulk-write.txt

@@ -0,0 +1,313 @@
+.. _php-bulk-write:
+
+=====================
+Bulk Write Operations
+=====================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: insert, update, replace, code example
+
+Overview
+--------
+
+In this guide, you can learn how to perform multiple write operations
+in a single database call by using **bulk write operations**.
+
+Consider a scenario in which you want to insert a document into a collection,
+update multiple other documents, then delete a document. If you use
+individual methods, each operation requires its own database call. Instead,
+you can use a bulk operation to reduce the number of calls to the database.
+
+Sample Data
+~~~~~~~~~~~
+
+The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants``
+database from the :atlas:`Atlas sample datasets </sample-data>`. To access this collection
+from your PHP application, instantiate a ``MongoDB\Client`` that connects to an Atlas cluster
+and assign the following value to your ``$collection`` variable:
+
+.. literalinclude:: /includes/write/bulk-write.php
+    :language: php
+    :dedent:
+    :start-after: start-db-coll
+    :end-before: end-db-coll
+
+To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the
+:atlas:`Get Started with Atlas </getting-started>` guide.
+
+.. _php-bulk-operations:
+
+Bulk Operations
+---------------
+
+To run a bulk write operation, pass an array of write operations to the
+``MongoDB\Collection::bulkWrite()`` method. You can specify the following
+operations in the array:
+
+.. code-block:: php
+
+   [
+       [ 'deleteMany' => [ $filter ] ],
+       [ 'deleteOne'  => [ $filter ] ],
+       [ 'insertOne'  => [ $document ] ],
+       [ 'replaceOne' => [ $filter, $replacement, $options ] ],
+       [ 'updateMany' => [ $filter, $update, $options ] ],
+       [ 'updateOne'  => [ $filter, $update, $options ] ],
+   ]
+
+.. tip::
+
+    For more information about delete, insert, replace, and update
+    operations, see the :ref:`Write operation guides <php-write>`.
+
+When you call the ``bulkWrite()`` method, the library automatically runs the
+write operations in the order they're specified in the array. To instruct ``bulkWrite()``
+to run the write operations in an arbitrary order, see the :ref:`php-bulk-modify` section.
+
+Example
+~~~~~~~
+
+The following example runs a delete, insert, and update operation on the
+``restaurants`` collection:
+
+.. literalinclude:: /includes/write/bulk-write.php
+   :start-after: start-bulk-insert-one
+   :end-before: end-bulk-insert-one
+   :language: php
+   :dedent:
+
+To insert multiple documents, create an instance of ``mongocxx::model::insert_one``
+for each document.
+
+.. _php-bulk-update-model:
+
+Update Operations
+~~~~~~~~~~~~~~~~~
+
+To update a document, create an instance of ``mongocxx::model::update_one``. This model
+instructs the driver to update *the first* document that matches your query filter. Then,
+append the model instance to an instance of the ``mongocxx::bulk_write`` class. 
+
+Pass the following arguments to the ``mongocxx::model::update_one`` model:
+
+- **Query filter** document, which specifies the criteria used to match documents
+  in your collection.
+- **Update** document, which specifies the kind of update to perform. For more information
+  about update operations, see the :manual:`Field Update Operators
+  </reference/operator/update-field/>` guide in the {+mdb-server+} manual.
+
+The following example creates an instance of ``mongocxx::model::update_one`` and appends
+it to a ``mongocxx::bulk_write`` instance called ``bulk``:
+
+.. literalinclude:: /includes/write/bulk-write.php
+   :start-after: start-bulk-update-one
+   :end-before: end-bulk-update-one
+   :language: php
+   :dedent:
+
+To update multiple documents, create an instance of ``mongocxx::model::update_many``
+and pass in the same arguments. This model instructs the driver to update *all* documents
+that match your query filter.
+
+The following example creates an instance of ``mongocxx::model::update_many`` and appends
+it to ``bulk``:
+
+.. literalinclude:: /includes/write/bulk-write.php
+   :start-after: start-bulk-update-many
+   :end-before: end-bulk-update-many
+   :language: php
+   :dedent:
+
+.. _php-bulk-replace-model:
+
+Replace Operations
+~~~~~~~~~~~~~~~~~~
+
+A replace operation removes all fields and values of a specified document and
+replaces them with new ones. To perform a replace operation, create an instance
+of the ``mongocxx::model::replace_one`` class and pass it a query filter and
+the fields and values you want to store in the matching document. Then, append
+the model instance to an instance of the ``mongocxx::bulk_write`` class.
+
+The following example creates an instance of ``mongocxx::model::replace_one`` and appends
+it to a ``mongocxx::bulk_write`` instance called ``bulk``:
+
+.. literalinclude:: /includes/write/bulk-write.php
+   :start-after: start-bulk-replace-one
+   :end-before: end-bulk-replace-one
+   :language: php
+   :dedent:
+
+To replace multiple documents, you must create a new instance of ``mongocxx::model::replace_one``
+for each document.
+
+.. _php-bulk-delete-model:
+
+Delete Operations
+~~~~~~~~~~~~~~~~~
+
+To delete a document, create an instance of the ``mongocxx::model::delete_one`` class and
+pass in a query filter specifying the document you want to delete. This model instructs
+the driver to delete only *the first* document that matches your query filter. Then, append
+the model instance to an instance of the ``mongocxx::bulk_write`` class.
+
+The following example creates an instance of ``mongocxx::model::delete_one`` and appends
+it to a ``mongocxx::bulk_write`` instance called ``bulk``:
+
+.. literalinclude:: /includes/write/bulk-write.php
+   :start-after: start-bulk-delete-one
+   :end-before: end-bulk-delete-one
+   :language: php
+   :dedent:
+
+To delete multiple documents, create an instance of the ``mongocxx::model::delete_many``
+class and pass in a query filter specifying the document you want to delete. This model
+instructs the driver to delete *all* documents that match your query filter.
+
+The following example creates an instance of ``mongocxx::model::delete_many`` and appends
+it to ``bulk``:
+
+.. literalinclude:: /includes/write/bulk-write.php
+   :start-after: start-bulk-delete-many
+   :end-before: end-bulk-delete-many
+   :language: php
+   :dedent:
+
+.. _php-bulk-modify:
+
+Modify Bulk Write Behavior
+--------------------------
+
+You can modify the behavior of the ``create_bulk_write()`` method by passing
+an instance of the ``mongocxx::options::bulk_write`` class as a parameter. The following
+table describes the fields you can set in a ``mongocxx::options::bulk_write``
+instance:
+
+.. list-table::
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Field
+     - Description
+
+   * - ``ordered``
+     - | If ``true``, the driver performs the write operations in the order
+         provided. If an error occurs, the remaining operations are not
+         attempted. 
+       |
+       | If ``false``, the driver performs the operations in an
+         arbitrary order and attempts to perform all operations.
+       | Defaults to ``true``.
+
+   * - ``bypass_document_validation``
+     - | Specifies whether the operation bypasses document-level validation. For more
+         information, see :manual:`Schema
+         Validation </core/schema-validation/#schema-validation>` in the MongoDB
+         Server manual.
+       | Defaults to ``false``.
+
+   * - ``write_concern``
+     - | Specifies the write concern for the bulk operation. For more information, see
+         :manual:`Write Concern </reference/write-concern/>` in the {+mdb-server+} manual.
+
+   * - ``comment``
+     - | Attaches a comment to the operation. For more information, see the :manual:`delete command
+         fields </reference/command/delete/#command-fields>` guide in the
+         {+mdb-server+} manual.
+
+   * - ``let``
+     - | Specifies a document with a list of values to improve operation readability. Values
+         must be constant or closed expressions that don't reference document fields. For more
+         information, see the :manual:`let statement
+         </reference/command/delete/#std-label-delete-let-syntax>` in the {+mdb-server+} manual.
+
+The following example calls the ``create_bulk_write()`` method from the
+:ref:`php-bulk-start-operation` example on this page, but sets the ``ordered`` field
+of a ``mongocxx::options::bulk_write`` instance to ``false``:
+
+.. literalinclude:: /includes/write/bulk-write.php
+   :start-after: start-bulk-write-unordered
+   :end-before: end-bulk-write-unordered
+   :language: php
+   :dedent:
+
+If any of the write operations in an unordered bulk write fail, the {+driver-short+}
+reports the errors only after attempting all operations.
+
+.. note::
+
+   Unordered bulk operations do not guarantee order of execution. The order can
+   differ from the way you list them to optimize the runtime.
+
+.. _php-bulk-return-value:
+
+Return Value
+------------
+
+The ``execute()`` method returns an instance of the ``mongocxx::result::bulk_write`` class.
+The ``mongocxx::result::bulk_write`` class contains the following member functions:
+
+.. list-table::
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Function
+     - Description
+         
+   * - ``deleted_count()``
+     - | Returns the number of documents deleted, if any.
+
+   * - ``inserted_count()``
+     - | Returns the number of documents inserted, if any.
+
+   * - ``matched_count()``
+     - | Returns the number of documents matched for an update, if applicable.
+
+   * - ``modified_count()``
+     - | Returns the number of documents modified, if any.
+
+   * - ``upserted_count()``
+     - | Returns the number of documents upserted, if any.
+
+   * - ``upserted_ids()``
+     - | Returns a map of the operation's index to the ``_id`` of the upserted documents, if
+         applicable.
+
+Additional Information
+----------------------
+
+To learn how to perform individual write operations, see the following guides:
+
+- :ref:`php-write-insert`
+- :ref:`php-write-update`
+- :ref:`php-write-delete`
+
+.. TODO:
+ - :ref:`php-write-replace`
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about any of the methods or types discussed in this
+guide, see the following API documentation:
+
+- `create_bulk_write() <{+api+}/classmongocxx_1_1v__noabi_1_1collection.html#abbf0932175201384cc902c80740adfdc>`__
+- `mongocxx::model::insert_one <{+api+}/classmongocxx_1_1v__noabi_1_1model_1_1insert__one.html>`__
+- `mongocxx::model::update_one <{+api+}/classmongocxx_1_1v__noabi_1_1model_1_1update__one.html>`__
+- `mongocxx::model::update_many <{+api+}/classmongocxx_1_1v__noabi_1_1model_1_1update__many.html>`__
+- `mongocxx::model::replace_one <{+api+}/classmongocxx_1_1v__noabi_1_1model_1_1replace__one.html>`__
+- `mongocxx::model::delete_one <{+api+}/classmongocxx_1_1v__noabi_1_1model_1_1delete__one.html>`__
+- `mongocxx::model::delete_many <{+api+}/classmongocxx_1_1v__noabi_1_1model_1_1delete__many.html>`__
+- `execute() <{+api+}/classmongocxx_1_1v__noabi_1_1bulk__write.html#a13476d87ed6d00dca52c39dc04b98568>`__
+- `mongocxx::options::bulk_write <{+api+}/classmongocxx_1_1v__noabi_1_1options_1_1bulk__write.html>`__
+- `mongocxx::result::bulk_write <{+api+}/classmongocxx_1_1v__noabi_1_1result_1_1bulk__write.html>`__