diff --git a/.github/workflows/vale-tdbx.yml b/.github/workflows/vale-tdbx.yml index 284033abe..8e4b6f491 100644 --- a/.github/workflows/vale-tdbx.yml +++ b/.github/workflows/vale-tdbx.yml @@ -12,6 +12,9 @@ jobs: - name: checkout uses: actions/checkout@master + - name: Install docutils + run: sudo apt-get install -y docutils + - id: files uses: masesgroup/retrieve-changed-files@v2 with: diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index cd590a53f..959d00468 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -10,28 +10,56 @@ Bulk Operations :depth: 2 :class: singlecol +.. meta:: + :keywords: insert, update, replace, code example, efficiency + Overview -------- In this guide, you can learn how to use bulk operations in the MongoDB Java Driver. -To perform a create, replace, update, or delete operation, -use its corresponding method. For example, to insert one document, -update multiple documents, and delete one document in your collection, -use the ``insertOne()``, ``updateMany()`` and ``deleteOne()`` methods. +To perform a single create, replace, update, or delete operation, you can use +the corresponding method. For example, to insert one document and replace one +document, you can use the ``insertOne()`` and ``replaceOne()`` methods. When you +use these methods, the ``MongoClient`` makes one call to the database for each operation. + +By using a bulk write operation, you can perform multiple write operations in +fewer database calls. You can perform bulk write operations at the following levels: + +- :ref:`Collection `: You can use the + ``MongoCollection.bulkWrite()`` method to perform bulk write operations on a + single collection. In this method, each kind of write operation requires at + least one database call. For example, ``MongoCollection.bulkWrite()`` puts multiple update + operations in one call, but makes two separate calls to the database for an insert + operation and a replace operation. -The ``MongoClient`` performs these operations by making a call for each -operation to the database. You can reduce the number of calls to the -database to one by using bulk operations. +- :ref:`Client `: If your application connects to + {+mdb-server+} version 8.0 or later, you can use the ``MongoClient.bulkWrite()`` + method to perform bulk write operations on multiple collections and databases + in the same cluster. This method performs all write operations + in one database call. -Performing Bulk Operations --------------------------- +.. _java-sync-coll-bulk-write: -Bulk operations consist of a large number of write operations. To perform -a bulk operation, pass a ``List`` of ``WriteModel`` documents to the -``bulkWrite()`` method. A ``WriteModel`` is a model that represents any -of the write operations. +Collection Bulk Write +--------------------- + +Bulk write operations contain one or more write operations. To perform a bulk +write operation at the collection level, pass a ``List`` of ``WriteModel`` +documents to the ``MongoCollection.bulkWrite()`` method. A ``WriteModel`` is a +model that represents a write operation. + +The ``MongoCollection.bulkWrite()`` method performs each kind of write +operation in a separate database call. For example, when you pass ``DeleteOneModel``, +``DeleteManyModel``, and ``ReplaceOneModel`` objects to the method, it performs +two calls: one for the delete operations and one for the replace operation. + +.. note:: + + When the client splits operations into separate database calls, it might + reorder operations for efficiency if the bulk write operation is not ordered. + To learn more about operation execution order, see the :ref:`orderOfExecution` section. The following sections show how to create and use each ``WriteModel`` document. The examples in each section use the following documents in the @@ -44,7 +72,7 @@ document. The examples in each section use the following documents in the { "_id": 8, "name": "Shayla Ray", "age": 20 } For more information about the methods and classes mentioned in this section, -see the following API Documentation: +see the following API documentation: - `bulkWrite() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#bulkWrite(java.util.List,com.mongodb.client.model.BulkWriteOptions)>`__ - `WriteModel <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/WriteModel.html>`__ @@ -100,7 +128,7 @@ describing people: For more information about the methods and classes mentioned in this section, see the `InsertOneModel <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/InsertOneModel.html>`__ -API Documentation. +API documentation. Replace Operation ~~~~~~~~~~~~~~~~~ @@ -132,7 +160,7 @@ contains an added ``location`` field: For more information about the methods and classes mentioned in this section, see the following resources: -- `ReplaceOneModel <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/ReplaceOneModel.html>`__ API Documentation +- `ReplaceOneModel <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/ReplaceOneModel.html>`__ API documentation - :manual:`Unique indexes ` Server Manual Explanation Update Operation @@ -168,8 +196,8 @@ the ``age`` field in a document where the ``_id`` is ``2``: For more information about the methods and classes mentioned in this section, see the following resources: -- `UpdateOneModel <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/UpdateOneModel.html>`__ API Documentation -- `UpdateManyModel <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/UpdateManyModel.html>`__ API Documentation +- `UpdateOneModel <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/UpdateOneModel.html>`__ API documentation +- `UpdateManyModel <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/UpdateManyModel.html>`__ API documentation - :manual:`unique indexes ` Server Manual Explanation Delete Operation @@ -202,7 +230,7 @@ a document where the ``_id`` is ``1``: :end-before: end deleteDocumentsExample For more information about the methods and classes mentioned in this section, -see the following API Documentation: +see the following API documentation: - `DeleteOneModel <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/DeleteOneModel.html>`__ - `DeleteManyModel <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/DeleteManyModel.html>`__ @@ -210,14 +238,14 @@ see the following API Documentation: .. _orderOfExecution: Order of Execution ------------------- +~~~~~~~~~~~~~~~~~~ The ``bulkWrite()`` method accepts an optional ``BulkWriteOptions`` as a second parameter to specify whether the execution of the bulk operations is -ordered or unordered. +ordered or unordered. Ordered Execution -~~~~~~~~~~~~~~~~~ ++++++++++++++++++ By default, the ``bulkWrite()`` method executes bulk operations in order. This means that the bulk operations execute in the order you @@ -253,7 +281,7 @@ document: { "_id": 6, "name": "Zaynab Hassan", "age": 37 } Unordered Execution -~~~~~~~~~~~~~~~~~~~ ++++++++++++++++++++ You can also execute bulk operations in any order by specifying "false" to the ``order()`` method on ``BulkWriteOptions``. This means that @@ -288,18 +316,255 @@ operations to execute in any order: { "_id": 6, "name": "Zaynab Omar", "age": 37 } For more information about the methods and classes mentioned in this section, -see the following API Documentation: +see the following API documentation: - `BulkWriteOptions <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/BulkWriteOptions.html>`__ - `ordered() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/BulkWriteOptions.html#ordered(boolean)>`__ +.. _java-sync-client-bulk-write: + +Client Bulk Write +----------------- + +When connecting to a deployment running {+mdb-server+} 8.0 or later, +you can use the ``MongoClient.bulkWrite()`` method to write +to multiple databases and collections in the same cluster. The ``MongoClient.bulkWrite()`` +method performs all write operations in a single call. + +The ``MongoClient.bulkWrite()`` method takes a +list of ``ClientNamespacedWriteModel`` instances to represent different write operations. +You can construct instances of the ``ClientNamespacedWriteModel`` interface by using +instance methods. For example, an instance of ``ClientNamespacedInsertOneModel`` represents an +operation to insert one document, and you can create this model by using +the ``ClientNamespacedWriteModel.insertOne()`` method. + +The models and their corresponding instance methods are described +in the table below. + +.. list-table:: + :header-rows: 1 + + * - Model + - Instance Method + - Description + - Parameters + + * - ``ClientNamespacedInsertOneModel`` + - ``insertOne()`` + - Creates a model to insert a document into the ``namespace``. + - ``namespace``: Database and collection to write to + + ``document``: Document to insert + + * - ``ClientNamespacedUpdateOneModel`` + - ``updateOne()`` + - Creates a model to update the first document in the ``namespace`` + that matches ``filter``. + - ``namespace``: Database and collection to write to + + ``filter``: Filter that selects which document to update + + ``update``: Update to apply to matching document + + ``updatePipeline``: Update pipeline to apply to matching document + + ``options``: (optional) Options to apply when updating document + + You must pass a value for either the ``update`` or ``updatePipeline`` + parameter. + + * - ``ClientNamespacedUpdateManyModel`` + - ``updateMany()`` + - Creates a model to update all documents in the ``namespace`` that match + ``filter``. + - ``namespace``: Database and collection to write to + + ``filter``: Filter that selects which documents to update + + ``update``: Update to apply to matching documents + + ``updatePipeline``: Update pipeline to apply to matching documents + + ``options``: (optional) Options to apply when updating documents + + You must pass a value for either the ``update`` or ``updatePipeline`` + parameter. + + * - ``ClientNamespacedReplaceOneModel`` + - ``replaceOne()`` + - Creates a model to replace the first document in the ``namespace`` that + matches ``filter``. + - ``namespace``: Database and collection to write to + + ``filter``: Filter that selects which document to replace + + ``replacement``: Replacement document + + ``options``: (optional) Options to apply when replacing documents + + * - ``ClientNamespacedDeleteOneModel`` + - ``deleteOne()`` + - Creates a model to delete the first document in the ``namespace`` that + matches ``filter``. + - ``namespace``: Database and collection to write to + + ``filter``: Filter that selects which document to delete + + ``option``: (optional) Options to apply when deleting document + + * - ``ClientNamespacedDeleteManyModel`` + - ``deleteMany()`` + - Creates a model to delete all documents in the ``namespace`` that match + ``filter``. + - ``namespace``: Database and collection to write to + + ``filter``: Filter that selects which documents to delete + + ``option``: (optional) Options to apply when deleting documents + +The following sections provide examples of how to use the client ``bulkWrite()`` +method. + +Insert Example +~~~~~~~~~~~~~~ + +This example shows how to use the ``bulkWrite()`` method to insert +two documents. One document is inserted into the ``db.people`` collection, while +the other document is inserted into the ``db.things`` collection. +The ``MongoNamespace`` instance defines the databases and collections that +each write operation applies to. + +.. code-block:: java + + MongoNamespace peopleNamespace = new MongoNamespace("db", "people"); + MongoNamespace thingsNamespace = new MongoNamespace("db", "things"); + + List bulkOperations = new ArrayList<>(); + + ClientNamespacedInsertOneModel insertDocument1 = new ClientNamespacedWriteModel + .insertOne( + peopleNamespace, + new Document("name", "Julia Smith") + ); + + ClientNamespacedInsertOneModel insertDocument2 = new ClientNamespacedWriteModel + .insertOne( + thingsNamespace, + new Document("object", "washing machine") + ); + + bulkOperations.add(insertDocument1); + bulkOperations.add(insertDocument2); + + ClientBulkWriteResult result = mongoClient.bulkWrite(bulkOperations); + +.. TODO: link documentation + +Replace Example +~~~~~~~~~~~~~~~ + +The following example shows how to use the ``bulkWrite()`` method to replace +existing documents in the ``db.people`` and ``db.things`` collections. + +.. code-block:: java + + MongoNamespace peopleNamespace = new MongoNamespace("db", "people"); + MongoNamespace thingsNamespace = new MongoNamespace("db", "things"); + + List bulkOperations = new ArrayList<>(); + + bulkOperations.add(ClientNamespacedWriteModel.replaceOne( + peopleNamespace, + Filters.eq("_id", 1), + new Document("name", "Frederic Hilbert") + ) + ); + + bulkOperations.add(ClientNamespacedWriteModel.replaceOne( + thingsNamespace, + Filters.eq("_id", 1), + new Document("object", "potato") + ) + ); + + ClientBulkWriteResult result = mongoClient.bulkWrite(bulkOperations); + +After this example runs successfully, the document that has an ``_id`` value of ``1`` +in the ``people`` collection is replaced with a new document. The document in +the ``things`` collection that has an ``_id`` value of ``1`` +is replaced with a new document. + +.. _java-sync-client-bulk-write-options: + +Bulk Write Options +~~~~~~~~~~~~~~~~~~ + +You can pass an instance of ``ClientBulkWriteOptions`` to the ``bulkWrite()`` +method to specify options when running the bulk write operations. + +Order of Execution Example +`````````````````````````` + +By default, the individual operations in a bulk operation are executed in the +order that you specify them until an error occurs, or until they execute +successfully. However, you can pass ``false`` to the ``ordered()`` method on +the ``ClientBulkWriteOptions`` interface to perform write operations in an +unordered way. When using the unordered option, an error-producing operation +does not prevent execution of other write operations in the call to the +``bulkWrite()`` method. + +The following code sets the ``ordered()`` method on an +instance of ``ClientBulkWriteOptions`` and performs a bulk write operation to +insert multiple documents. + +.. code-block:: java + + MongoNamespace namespace = new MongoNamespace("db", "people"); + + ClientBulkWriteOptions options = new ClientBulkWriteOptions().ordered(false); + + List bulkOperations = new ArrayList<>(); + + bulkOperations.add( + ClientNamespacedWriteModel.insertOne( + namespace, + new Document("_id", 1).append("name", "Rudra Suraj") + ) + ); + + // Causes a duplicate key error + bulkOperations.add( + ClientNamespacedWriteModel.insertOne( + namespace, + new Document("_id", 1).append("name", "Mario Bianchi") + ) + ); + + bulkOperations.add( + ClientNamespacedWriteModel.insertOne( + namespace, + new Document("name", "Wendy Zhang") + ) + ); + + ClientBulkWriteResult result = mongoClient.bulkWrite(bulkOperations, options); + +Even though the write operation inserting a document with a duplicate key results +in an error, the other operations are executed because the write operation is +unordered. + +.. TODO: link documentation + Summary ------- +``MongoCollection.bulkWrite()`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + To perform a bulk operation, you create and pass a list of -``WriteModel`` documents to the ``bulkWrite()`` method. +``WriteModel`` instances to the ``bulkWrite()`` method. -There are 6 different ``WriteModel`` documents: ``InsertOneModel``, +There are 6 different ``WriteModel`` subtypes: ``InsertOneModel``, ``ReplaceOneModel``, ``UpdateOneModel``, ``UpdateManyModel``, ``DeleteOneModel`` and ``DeleteManyModel``. @@ -308,3 +573,29 @@ There are two ways to execute the ``bulkWrite()`` method: - Ordered, which performs the bulk operations in order until an error occurs, if any - Unordered, which performs all the bulk operations in any order and reports errors at the end, if any + +``MongoClient.bulkWrite()`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When connecting to a deployment running {+mdb-server+} version 8.0 or later, you +can use the ``MongoClient.bulkWrite()`` method to perform bulk operations on multiple +databases and collections at once. + +To perform a client bulk operation, you create an pass a list of +``ClientNamespacedWriteModel`` instances to this method. + +There are six subtypes of ``ClientNamespacedWriteModel`` that are used to +represent write operations. To construct these write models, you can use the +corresponding ``ClientNamespacedWriteModel`` methods ``insertOne()``, ``updateOne()``, +``updateMany()``, ``replaceOne()``, ``deleteOne()``, and ``deleteMany()``. These +methods take a ``MongoNamespace`` object that defines which +database and collection to write to. + +The ``MongoClient.bulkWrite()`` method can also take a ``ClientBulkWriteOptions`` +object to specify different options for how the command is executed. + +To learn more about the client ``bulkWrite`` command, see the +:manual:`bulkWrite() ` method reference in the {+mdb-server+} +Manual. + +.. TODO: Add API Documentation diff --git a/source/whats-new.txt b/source/whats-new.txt index 8850468ae..a048c6f35 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -19,6 +19,7 @@ What's New Learn what's new in: +* :ref:`Version 5.3 ` * :ref:`Version 5.2.1 ` * :ref:`Version 5.2 ` * :ref:`Version 5.1.3 ` @@ -29,6 +30,18 @@ Learn what's new in: * :ref:`Version 4.11 ` * :ref:`Version 4.10 ` +.. _java-version-5.3: + +What's New in 5.3 +----------------- + +The 5.3 {+driver-short+} release introduces the following improvements, features, +and fixes: + +- Client bulk write API that allows you to perform write operations on multiple + databases and collections at once. To learn more about this feature, see the + :ref:`java-sync-client-bulk-write` section of the Bulk Operations guide. + .. _java-version-5.2.1: What's New in 5.2.1