From 72b9e7301d82ad24030794a66f994d861adab74c Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Mon, 11 Nov 2024 11:36:38 -0500 Subject: [PATCH 01/23] initial checkpoint --- .../crud/write-operations/bulk.txt | 87 ++++++++++++++++++- 1 file changed, 86 insertions(+), 1 deletion(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index cd590a53f..c1997a604 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -16,6 +16,15 @@ Overview In this guide, you can learn how to use bulk operations in the MongoDB Java Driver. +.. note:: Improved Bulk Write Commands + + In {+driver-short+} version 5.3 and later, you can use the + ``ClientNamespacedWriteModel`` object to represent the write + operations. See the :ref:`improved-bulk-write` section below + to see how to use this object. + + + 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, @@ -44,7 +53,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>`__ @@ -293,6 +302,80 @@ 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)>`__ +.. _improved-bulk-write: + +Improved Bulk Write Command +--------------------------- + +.. specify which library + +Starting with {+mdb-server+} version 8.0 and {+driver-short+} version 5.3, the +``bulkWrite()`` method can be used in a different way. There are four ways in +which you can call this method: + +.. TODO: describe how these can be used to write to different collections at +.. the same time + +.. TODO: Namespace vs not namespace write model + +bulkWrite(models) +~~~~~~~~~~~~~~~~~ + +In the previous examples on this page, the ``bulkWrite()`` method takes a list +of ``WriteModel`` documents. In these examples, the specified subclass of +``WriteModel`` represents the corresponding write operation, like ``InsertOneModel`` +represents inserting one document. + +Now, ``bulkWrite()`` can take a list of ``ClientWriteModel`` objects. Instead +of having to specify different subclasses, this object has different methods to +represent different write operations, such as ``insertOne()`` or ``updateOne()``. +These methods take a ``MongoNamespace`` object that defines which database and +collection to write to and a ``Document`` object that defines the document. + +The following example shows how to use ``ClientWriteModel`` to insert two documents +into the ``people`` collection of our database: + +.. code-block:: java + MongoNamespace namespace = new MongoNamespace("db", "people"); + + ClientBulkWriteResult result = client.bulkWrite(List<>( + ClientNamespacedWriteModel.insertOne(namespace, new Document("name", "Julia Smith")), + ClientNamespacedWriteModel.insertOne(namespace, new Document("name", "Blablabla")) + )); + +.. TODO: move code to includes + +.. TODO: link documentation + +bulkWrite(models, options) +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Similarly to the :ref:`orderOfExecution` above, you can use the ``ClientBulkWriteOptions`` +object to add options to your call of the new ``bulkWrite()`` method. + +As described above, by default the write operations execute in the order they're +specified. However, we can specify ``false`` to the ``ordered()`` method on the +``ClientBulkWriteOptions`` object to execute write operations in any order. + +.. code-block:: java + MongoNamespace namespace = new MongoNamespace("db", "people"); + + ClientBulkWriteOptions options = new ClientBulkWriteOptions().ordered(false); + + + ClientBulkWriteResult result = client.bulkWrite(List<>( + ClientNamespacedWriteModel.insertOne(namespace, new Document("name", "Julia Smith")), + ClientNamespacedWriteModel.insertOne(namespace, new Document("name", "Blablabla")) + ), + options); + +.. TODO: add one more example? + +.. TODO: link documentation + +.. TODO; also results and error types + + Summary ------- @@ -308,3 +391,5 @@ 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 + +.. TODO: summarize results in a table i think \ No newline at end of file From 09d5786f7f97abc3cc05dbde56fb8cd28d2f1d3b Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Mon, 11 Nov 2024 17:15:15 -0500 Subject: [PATCH 02/23] Initial full pass --- .../crud/write-operations/bulk.txt | 152 ++++++++++++------ source/whats-new.txt | 11 ++ 2 files changed, 117 insertions(+), 46 deletions(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index c1997a604..f08ff28b3 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -18,12 +18,11 @@ MongoDB Java Driver. .. note:: Improved Bulk Write Commands - In {+driver-short+} version 5.3 and later, you can use the - ``ClientNamespacedWriteModel`` object to represent the write - operations. See the :ref:`improved-bulk-write` section below - to see how to use this object. - - + The first half of this guide focuses on the ``MongoCollection.bulkWrite()`` + method. In {+mdb-server+} version 8.0 and {+driver-short+} version 5.3 and later, + you can use an improved ``MongoClient.bulkWrite()`` method which can write + to multiple databases and collections at once. See the :ref:`improved-bulk-write` + section below to learn how to use the new method. To perform a create, replace, update, or delete operation, use its corresponding method. For example, to insert one document, @@ -307,55 +306,98 @@ see the following API Documentation: Improved Bulk Write Command --------------------------- -.. specify which library +Starting with {+mdb-server+} version 8.0 and {+driver-short+} version 5.3, there +is an improved bulk write method, ``MongoClient.bulkWrite()``, that can be used +to write to different databases and collections in the same cluster. -Starting with {+mdb-server+} version 8.0 and {+driver-short+} version 5.3, the -``bulkWrite()`` method can be used in a different way. There are four ways in -which you can call this method: +In the previous examples on this page, the ``bulkWrite()`` method takes a list +of ``WriteModel`` documents. The specified subclass of ``WriteModel`` represents +the corresponding write operation. For example, ``InsertOneModel`` represents +inserting one document. Similarly, the new ``bulkWrite()`` method takes a +list of ``ClientNamespacedWriteModel`` objects to represent the write operation. +However, you do not need to specify the subclass that represents the corresponding +write operation. Instead, the ``ClientNamespacedWriteModel`` object contains different +methods to represent different write operations, such as ``insertOne()`` or +``updateOne()``. These methods take a ``MongoNamespace object that defines which +database and collection to write to and a ``Document`` object that defines the +document information. Some methods, such as ``updateOne()`` and ``replaceOne()``, +also take a ``filter`` object. + +The following sections describe how to use the new ``bulkWrite()`` method. + +Insert Example +~~~~~~~~~~~~~~ + +The following example shows how to use the new ``bulkWrite()`` method to insert +two documents. One document is inserted into the ``people`` collection in our +database. The other document is inserted into a collection called ``things``. +We use the ``MongoNamespace`` object to define the database and collection we +want each write operation to be applied to. -.. TODO: describe how these can be used to write to different collections at -.. the same time +.. code-block:: java -.. TODO: Namespace vs not namespace write model + MongoNamespace peopleNamespace = new MongoNamespace("db", "people"); + MongoNamespace thingsNamespace = new MongoNamespace("db", "things"); -bulkWrite(models) -~~~~~~~~~~~~~~~~~ + ClientBulkWriteResult result = client.bulkWrite(List<>( + ClientNamespacedWriteModel.insertOne(peopleNamespace, new Document("name", "Julia Smith")), + ClientNamespacedWriteModel.insertOne(thingsNamespace, new Document("object", "washing machine")) + )); -In the previous examples on this page, the ``bulkWrite()`` method takes a list -of ``WriteModel`` documents. In these examples, the specified subclass of -``WriteModel`` represents the corresponding write operation, like ``InsertOneModel`` -represents inserting one document. +After this example is executed, the ``people`` collection holds a +``{ "name": "Julia Smith" }`` document and the ``things`` collection holds +a ``{ "object": "washing machine" }`` document. + +.. TODO: link documentation -Now, ``bulkWrite()`` can take a list of ``ClientWriteModel`` objects. Instead -of having to specify different subclasses, this object has different methods to -represent different write operations, such as ``insertOne()`` or ``updateOne()``. -These methods take a ``MongoNamespace`` object that defines which database and -collection to write to and a ``Document`` object that defines the document. +Replace Example +~~~~~~~~~~~~~~~ -The following example shows how to use ``ClientWriteModel`` to insert two documents -into the ``people`` collection of our database: +The following example shows how to use the ``bulkWrite()`` method to replace an +existing document in the ``people`` collection and an existing document in the +``things`` collection. .. code-block:: java - MongoNamespace namespace = new MongoNamespace("db", "people"); + + MongoNamespace peopleNamespace = new MongoNamespace("db", "people"); + MongoNamespace thingsNamespace = new MongoNamespace("db", "things"); ClientBulkWriteResult result = client.bulkWrite(List<>( - ClientNamespacedWriteModel.insertOne(namespace, new Document("name", "Julia Smith")), - ClientNamespacedWriteModel.insertOne(namespace, new Document("name", "Blablabla")) + ClientNamespacedWriteModel.replaceOne( + peopleNamespace, + Filters.eq("_id", 1), + new Document("name", "Maximus Farquaad") + ), + ClientNamespacedWriteModel.replaceOne( + thingsNamespace, + Filters.eq("_id", 1), + new Document("object", "potato") + ) )); -.. TODO: move code to includes +After this example is executed, the document in the ``people`` collection in +which the ``_id`` field has the value of ``1`` has been replaced with a new +``{ "name": "Maximus Farquaad" }`` document. Also, the document +in the ``things`` collection in which the ``_id`` field has the value of ``1`` +has been replaced with a ``{ "object": "potato" }`` document. -.. TODO: link documentation +Bulk Write Options +~~~~~~~~~~~~~~~~~~ + +Similarly to the :ref:`orderOfExecution` section above, you can use the +``ClientBulkWriteOptions`` object to execute the new ``bulkWrite()`` method +with options. -bulkWrite(models, options) -~~~~~~~~~~~~~~~~~~~~~~~~~~ +Order of Execution Example +`````````````````````````` -Similarly to the :ref:`orderOfExecution` above, you can use the ``ClientBulkWriteOptions`` -object to add options to your call of the new ``bulkWrite()`` method. +As described in the previous Order of Execution section, by default the write +operations execute in the order they're specified. However, we can pass +``false`` to the ``ordered()`` method on the ``ClientBulkWriteOptions`` object +to execute write operations in any order. -As described above, by default the write operations execute in the order they're -specified. However, we can specify ``false`` to the ``ordered()`` method on the -``ClientBulkWriteOptions`` object to execute write operations in any order. +The following code shows how to use the ``ordered()`` method on the +``ClientBulkWriteOptions`` object. .. code-block:: java MongoNamespace namespace = new MongoNamespace("db", "people"); @@ -364,21 +406,19 @@ specified. However, we can specify ``false`` to the ``ordered()`` method on the ClientBulkWriteResult result = client.bulkWrite(List<>( - ClientNamespacedWriteModel.insertOne(namespace, new Document("name", "Julia Smith")), - ClientNamespacedWriteModel.insertOne(namespace, new Document("name", "Blablabla")) + ClientNamespacedWriteModel.insertOne(namespace, new Document("name", "Donkey Kong")), + ClientNamespacedWriteModel.insertOne(namespace, new Document("name", "Mario")) ), options); -.. TODO: add one more example? - .. TODO: link documentation -.. TODO; also results and error types - - Summary ------- +``MongoCollection.bulkWrite()`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + To perform a bulk operation, you create and pass a list of ``WriteModel`` documents to the ``bulkWrite()`` method. @@ -392,4 +432,24 @@ There are two ways to execute the ``bulkWrite()`` method: - Unordered, which performs all the bulk operations in any order and reports errors at the end, if any -.. TODO: summarize results in a table i think \ No newline at end of file +``MongoClient.bulkWrite()`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In {+mdb-server+} version 8.0 and {+driver-short+} version 5.3 and later, you +can use the ``bulkWrite()`` method to perform bulk operations on multiple +databases and collections at once. + +This method uses the ``ClientNamespacedWriteModel`` and its methods +``insertOne()``, ``updateOne()``, ``updateMany()``, ``replaceOne()``, +``deleteOne()``, and ``deleteMany()``. + +The method can also take a ``ClientBulkWriteOptions`` object to specify different +options for how the command is executed. + +.. TODO: Add API Documentation + +.. OPEN QUESTIONS FOR ENGINEERING: + .. Should I include the extraneous types like the Client...Result object? + .. Should I include the different ClientNamespacedInsertModel... etc? + .. Is ClientWriteModel being exposed for public use? + .. Is MongoCollection.bulkWrite() being deprecated? diff --git a/source/whats-new.txt b/source/whats-new.txt index 96251db7b..761e4bb85 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,16 @@ Learn what's new in: * :ref:`Version 4.11 ` * :ref:`Version 4.10 ` +.. _java-version-5.3: + +What's New in 5.3 +----------------- + +New features of the 5.3 release include: + +- A new :ref:`bulk write command ` that can perform bulk + write operations on multiple databases and collections at once. + .. _java-version-5.2.1: What's New in 5.2.1 From 161ffec0daf245d4e429d2f03480c624356a7d11 Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Mon, 11 Nov 2024 17:34:11 -0500 Subject: [PATCH 03/23] first pass edits --- .../crud/write-operations/bulk.txt | 22 +++++++++++-------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index f08ff28b3..ce3b4e1d4 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -307,21 +307,25 @@ Improved Bulk Write Command --------------------------- Starting with {+mdb-server+} version 8.0 and {+driver-short+} version 5.3, there -is an improved bulk write method, ``MongoClient.bulkWrite()``, that can be used -to write to different databases and collections in the same cluster. +is an improved bulk write method, ``MongoClient.bulkWrite()``, that writes to +different databases and collections in the same cluster. In the previous examples on this page, the ``bulkWrite()`` method takes a list -of ``WriteModel`` documents. The specified subclass of ``WriteModel`` represents -the corresponding write operation. For example, ``InsertOneModel`` represents -inserting one document. Similarly, the new ``bulkWrite()`` method takes a +of ``WriteModel`` documents in which the specified subclass of ``WriteModel`` +represents the corresponding write operation. For example, ``InsertOneModel`` +represents inserting one document. + +Similarly, the new ``bulkWrite()`` method takes a list of ``ClientNamespacedWriteModel`` objects to represent the write operation. However, you do not need to specify the subclass that represents the corresponding write operation. Instead, the ``ClientNamespacedWriteModel`` object contains different methods to represent different write operations, such as ``insertOne()`` or -``updateOne()``. These methods take a ``MongoNamespace object that defines which -database and collection to write to and a ``Document`` object that defines the +``updateOne()``. + +These methods take a ``MongoNamespace`` object that defines which +database and collection to write to, and a ``Document`` object that defines the document information. Some methods, such as ``updateOne()`` and ``replaceOne()``, -also take a ``filter`` object. +also take a ``Filters`` object that defines the filter for the operation. The following sections describe how to use the new ``bulkWrite()`` method. @@ -400,11 +404,11 @@ The following code shows how to use the ``ordered()`` method on the ``ClientBulkWriteOptions`` object. .. code-block:: java + MongoNamespace namespace = new MongoNamespace("db", "people"); ClientBulkWriteOptions options = new ClientBulkWriteOptions().ordered(false); - ClientBulkWriteResult result = client.bulkWrite(List<>( ClientNamespacedWriteModel.insertOne(namespace, new Document("name", "Donkey Kong")), ClientNamespacedWriteModel.insertOne(namespace, new Document("name", "Mario")) From 9d37fac9ba52c22d25068d34d9ca0c0964b4bd7a Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Wed, 13 Nov 2024 16:00:04 -0500 Subject: [PATCH 04/23] feedback initial pass --- .../crud/write-operations/bulk.txt | 120 +++++++++--------- source/whats-new.txt | 12 +- 2 files changed, 72 insertions(+), 60 deletions(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index ce3b4e1d4..86c661f0a 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -16,13 +16,15 @@ Overview In this guide, you can learn how to use bulk operations in the MongoDB Java Driver. -.. note:: Improved Bulk Write Commands +.. note:: Client Bulk Write Method - The first half of this guide focuses on the ``MongoCollection.bulkWrite()`` - method. In {+mdb-server+} version 8.0 and {+driver-short+} version 5.3 and later, - you can use an improved ``MongoClient.bulkWrite()`` method which can write - to multiple databases and collections at once. See the :ref:`improved-bulk-write` - section below to learn how to use the new method. + This guide primarily focuses on the ``MongoCollection.bulkWrite()`` + method, which allows you to perform bulk operations on a collection. + 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 call. See the + :ref:`java-sync-client-bulk-write` section below to learn how to use the + ``MongoClient.bulkWrite()`` method. To perform a create, replace, update, or delete operation, use its corresponding method. For example, to insert one document, @@ -108,7 +110,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 ~~~~~~~~~~~~~~~~~ @@ -140,7 +142,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 @@ -176,8 +178,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 @@ -210,7 +212,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>`__ @@ -296,45 +298,48 @@ 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)>`__ -.. _improved-bulk-write: +.. _java-sync-client-bulk-write: -Improved Bulk Write Command ---------------------------- +Client Bulk Write Method +------------------------ -Starting with {+mdb-server+} version 8.0 and {+driver-short+} version 5.3, there -is an improved bulk write method, ``MongoClient.bulkWrite()``, that writes to -different databases and collections in the same cluster. +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. -In the previous examples on this page, the ``bulkWrite()`` method takes a list -of ``WriteModel`` documents in which the specified subclass of ``WriteModel`` -represents the corresponding write operation. For example, ``InsertOneModel`` -represents inserting one document. +In the examples in preceding sections of this page, the ``MongoCollection.bulkWrite()`` method +takes a list of ``WriteModel`` documents in which the specified subclass of +``WriteModel`` represents the corresponding write operation. For example, an +instance of ``InsertOneModel`` represents an operation to insert one document. -Similarly, the new ``bulkWrite()`` method takes a -list of ``ClientNamespacedWriteModel`` objects to represent the write operation. +.. TODO - not necessarily instances + +Similarly, the ``MongoClient.bulkWrite()`` method takes a +list of ``ClientNamespacedWriteModel`` instances to represent different write operations. However, you do not need to specify the subclass that represents the corresponding write operation. Instead, the ``ClientNamespacedWriteModel`` object contains different methods to represent different write operations, such as ``insertOne()`` or ``updateOne()``. These methods take a ``MongoNamespace`` object that defines which -database and collection to write to, and a ``Document`` object that defines the -document information. Some methods, such as ``updateOne()`` and ``replaceOne()``, -also take a ``Filters`` object that defines the filter for the operation. +database and collection to write to, and a ``Document`` object that defines +information about the write operation. Some methods, such as ``updateOne()`` and +``replaceOne()``, also take a ``Filters`` object that defines the filter for the operation. -The following sections describe how to use the new ``bulkWrite()`` method. +The following sections describe how to use the client ``bulkWrite()`` method. Insert Example ~~~~~~~~~~~~~~ -The following example shows how to use the new ``bulkWrite()`` method to insert -two documents. One document is inserted into the ``people`` collection in our -database. The other document is inserted into a collection called ``things``. +This following example shows how to use the ``bulkWrite()`` method to insert +two documents. One document is inserted into the ``people`` collection in a +database named ``db``. The other document is inserted into a collection called ``things`` +in the ``db`` database. We use the ``MongoNamespace`` object to define the database and collection we want each write operation to be applied to. @@ -348,18 +353,13 @@ want each write operation to be applied to. ClientNamespacedWriteModel.insertOne(thingsNamespace, new Document("object", "washing machine")) )); -After this example is executed, the ``people`` collection holds a -``{ "name": "Julia Smith" }`` document and the ``things`` collection holds -a ``{ "object": "washing machine" }`` document. - .. TODO: link documentation Replace Example ~~~~~~~~~~~~~~~ -The following example shows how to use the ``bulkWrite()`` method to replace an -existing document in the ``people`` collection and an existing document in the -``things`` collection. +The following example shows how to use the ``bulkWrite()`` method to replace +existing documents in the ``people`` and ``things`` collections. .. code-block:: java @@ -379,28 +379,32 @@ existing document in the ``people`` collection and an existing document in the ) )); -After this example is executed, the document in the ``people`` collection in -which the ``_id`` field has the value of ``1`` has been replaced with a new -``{ "name": "Maximus Farquaad" }`` document. Also, the document -in the ``things`` collection in which the ``_id`` field has the value of ``1`` -has been replaced with a ``{ "object": "potato" }`` document. +After this example runs successfully, the document in the ``people`` collection in +which the ``_id`` field has the value of ``1`` is replaced with a new +document. The document in the ``things`` collection in which the +``_id`` field has the value of ``1`` is replaced with a new document. + +.. _java-sync-client-bulk-write-options: Bulk Write Options ~~~~~~~~~~~~~~~~~~ -Similarly to the :ref:`orderOfExecution` section above, you can use the -``ClientBulkWriteOptions`` object to execute the new ``bulkWrite()`` method -with options. +.. TODO: reword this + +You can use the ``ClientBulkWriteOptions`` object to execute the ``bulkWrite()`` +method with options. Order of Execution Example `````````````````````````` +By default, the write operations execute in the order that you specify them. However, +you can pass ``false`` to the ``ordered()`` method on the ``ClientBulkWriteOptions`` +object to perform write operations in an unordered way. When using the unordered +option, an error-producing operation will not block execution of other bulk +write operations. -As described in the previous Order of Execution section, by default the write -operations execute in the order they're specified. However, we can pass -``false`` to the ``ordered()`` method on the ``ClientBulkWriteOptions`` object -to execute write operations in any order. +.. TODO: the object itself is not necessarily being created -The following code shows how to use the ``ordered()`` method on the +The following code shows how to set the ``ordered()`` method on the ``ClientBulkWriteOptions`` object. .. code-block:: java @@ -409,11 +413,13 @@ The following code shows how to use the ``ordered()`` method on the ClientBulkWriteOptions options = new ClientBulkWriteOptions().ordered(false); - ClientBulkWriteResult result = client.bulkWrite(List<>( - ClientNamespacedWriteModel.insertOne(namespace, new Document("name", "Donkey Kong")), - ClientNamespacedWriteModel.insertOne(namespace, new Document("name", "Mario")) + ClientBulkWriteResult result = client.bulkWrite( + List<>( + ClientNamespacedWriteModel.insertOne(namespace, new Document("name", "Donkey Kong")), + ClientNamespacedWriteModel.insertOne(namespace, new Document("name", "Mario")) ), - options); + options + ); .. TODO: link documentation @@ -455,5 +461,5 @@ options for how the command is executed. .. OPEN QUESTIONS FOR ENGINEERING: .. Should I include the extraneous types like the Client...Result object? .. Should I include the different ClientNamespacedInsertModel... etc? - .. Is ClientWriteModel being exposed for public use? - .. Is MongoCollection.bulkWrite() being deprecated? + .. Is ClientWriteModel being exposed for public use? + .. Is MongoCollection.bulkWrite() being deprecated? diff --git a/source/whats-new.txt b/source/whats-new.txt index 761e4bb85..1d4eb7ccc 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -35,10 +35,16 @@ Learn what's new in: What's New in 5.3 ----------------- -New features of the 5.3 release include: +The 5.3 {+driver-short+} release introduces the following improvements, features, +and fixes: -- A new :ref:`bulk write command ` that can perform bulk - write operations on multiple databases and collections at once. +- 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. + +- A ``ClientBulkWriteOptions`` object to specify different options for how + the client bulk write API is executed. See the :ref:`java-sync-client-bulk-write-options` + section of the Client Bulk Write guide. .. _java-version-5.2.1: From 5e577ba13d5605f329e74e2ea6b419002f7bfbb2 Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Wed, 13 Nov 2024 18:02:30 -0500 Subject: [PATCH 05/23] finished feedback --- .../crud/write-operations/bulk.txt | 79 ++++++++++--------- 1 file changed, 42 insertions(+), 37 deletions(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index 86c661f0a..1f88ca3e6 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -313,18 +313,16 @@ you can use the ``MongoClient.bulkWrite()`` method to write to multiple databases and collections in the same cluster. In the examples in preceding sections of this page, the ``MongoCollection.bulkWrite()`` method -takes a list of ``WriteModel`` documents in which the specified subclass of +takes a list of ``WriteModel`` instances in which the specified subclass of ``WriteModel`` represents the corresponding write operation. For example, an instance of ``InsertOneModel`` represents an operation to insert one document. -.. TODO - not necessarily instances - Similarly, the ``MongoClient.bulkWrite()`` method takes a -list of ``ClientNamespacedWriteModel`` instances to represent different write operations. +list of ``ClientNamespacedWriteModel`` instances to represent different write operations. However, you do not need to specify the subclass that represents the corresponding write operation. Instead, the ``ClientNamespacedWriteModel`` object contains different -methods to represent different write operations, such as ``insertOne()`` or -``updateOne()``. +methods to represent different write operations, such as ``ClientNamespacedWriteModel.insertOne()`` or +``ClientNamespacedWriteModel.updateOne()``. These methods take a ``MongoNamespace`` object that defines which database and collection to write to, and a ``Document`` object that defines @@ -348,10 +346,12 @@ want each write operation to be applied to. MongoNamespace peopleNamespace = new MongoNamespace("db", "people"); MongoNamespace thingsNamespace = new MongoNamespace("db", "things"); - ClientBulkWriteResult result = client.bulkWrite(List<>( - ClientNamespacedWriteModel.insertOne(peopleNamespace, new Document("name", "Julia Smith")), - ClientNamespacedWriteModel.insertOne(thingsNamespace, new Document("object", "washing machine")) - )); + List bulkOperations = new ArrayList<>(); + + bulkOperations.add(ClientNamespacedWriteModel.insertOne(peopleNamespace, new Document("name", "Julia Smith"))); + bulkOperations.add(ClientNamespacedWriteModel.insertOne(thingsNamespace, new Document("object", "washing machine"))); + + ClientBulkWriteResult result = client.bulkWrite(bulkOperations); .. TODO: link documentation @@ -366,18 +366,23 @@ existing documents in the ``people`` and ``things`` collections. MongoNamespace peopleNamespace = new MongoNamespace("db", "people"); MongoNamespace thingsNamespace = new MongoNamespace("db", "things"); - ClientBulkWriteResult result = client.bulkWrite(List<>( - ClientNamespacedWriteModel.replaceOne( + List bulkOperations = new ArrayList<>(); + + bulkOperations.add(ClientNamespacedWriteModel.replaceOne( peopleNamespace, Filters.eq("_id", 1), new Document("name", "Maximus Farquaad") - ), - ClientNamespacedWriteModel.replaceOne( + ) + ); + + bulkOperations.add(ClientNamespacedWriteModel.replaceOne( thingsNamespace, Filters.eq("_id", 1), new Document("object", "potato") ) - )); + ); + + ClientBulkWriteResult result = client.bulkWrite(bulkOperations); After this example runs successfully, the document in the ``people`` collection in which the ``_id`` field has the value of ``1`` is replaced with a new @@ -389,23 +394,20 @@ document. The document in the ``things`` collection in which the Bulk Write Options ~~~~~~~~~~~~~~~~~~ -.. TODO: reword this - -You can use the ``ClientBulkWriteOptions`` object to execute the ``bulkWrite()`` -method with options. +You can use the ``ClientBulkWriteOptions`` interface to specify options when +running the ``bulkWrite()`` method. Order of Execution Example `````````````````````````` + By default, the write operations execute in the order that you specify them. However, you can pass ``false`` to the ``ordered()`` method on the ``ClientBulkWriteOptions`` -object to perform write operations in an unordered way. When using the unordered +interface to perform write operations in an unordered way. When using the unordered option, an error-producing operation will not block execution of other bulk write operations. -.. TODO: the object itself is not necessarily being created - -The following code shows how to set the ``ordered()`` method on the -``ClientBulkWriteOptions`` object. +The following code shows how to set the ``ordered()`` method when creating an +instance of ``ClientBulkWriteOptions``. .. code-block:: java @@ -413,13 +415,20 @@ The following code shows how to set the ``ordered()`` method on the ClientBulkWriteOptions options = new ClientBulkWriteOptions().ordered(false); - ClientBulkWriteResult result = client.bulkWrite( - List<>( - ClientNamespacedWriteModel.insertOne(namespace, new Document("name", "Donkey Kong")), - ClientNamespacedWriteModel.insertOne(namespace, new Document("name", "Mario")) - ), - options - ); + List bulkOperations = new ArrayList<>(); + + bulkOperations.add(ClientNamespacedWriteModel.insertOne(namespace, new Document("_id", 1).append("name", "Donkey Kong))); + + // duplicate key + bulkOperations.add(ClientNamespacedWriteModel.insertOne(namespace, new Document("_id", 1).append("name", "Mario"))); + + bulkOperations.add(ClientNamespacedWriteModel.insertOne(namespace, new Document("name", "Princess Peach"))); + + ClientBulkWriteResult result = client.bulkWrite(bulkOperations, options); + +Even though the write operation inserting a document with a duplicate key will +result in an error, the other operations will be executed because we have specified +the ``ordered()`` option to be ``false``. .. TODO: link documentation @@ -456,10 +465,6 @@ This method uses the ``ClientNamespacedWriteModel`` and its methods The method can also take a ``ClientBulkWriteOptions`` object to specify different options for how the command is executed. -.. TODO: Add API Documentation +.. TODO: insert server documentation -.. OPEN QUESTIONS FOR ENGINEERING: - .. Should I include the extraneous types like the Client...Result object? - .. Should I include the different ClientNamespacedInsertModel... etc? - .. Is ClientWriteModel being exposed for public use? - .. Is MongoCollection.bulkWrite() being deprecated? +.. TODO: Add API Documentation From 78d26c06095f6a09f886ca0347a8d9aa679fa31f Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Wed, 13 Nov 2024 18:11:21 -0500 Subject: [PATCH 06/23] manual --- source/fundamentals/crud/write-operations/bulk.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index 1f88ca3e6..e2e8276fe 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -465,6 +465,8 @@ This method uses the ``ClientNamespacedWriteModel`` and its methods The method can also take a ``ClientBulkWriteOptions`` object to specify different options for how the command is executed. -.. TODO: insert server documentation +To learn more about the client ``bulkWrite`` command, take a look at the +:manual:`bulkWrite ` guide in the {+mdb-server+} +Manual. .. TODO: Add API Documentation From db24b1ed26889f711d33968041ce8bba17ebca79 Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Thu, 14 Nov 2024 13:06:34 -0500 Subject: [PATCH 07/23] feedback part 2 --- .../crud/write-operations/bulk.txt | 130 ++++++++++-------- source/whats-new.txt | 4 - 2 files changed, 72 insertions(+), 62 deletions(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index e2e8276fe..98446ceb4 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -16,32 +16,33 @@ Overview In this guide, you can learn how to use bulk operations in the MongoDB Java Driver. -.. note:: Client Bulk Write Method +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. The +``MongoClient`` makes a call to the database for each operation. You can reduce +the number of calls to one by using bulk write operations. - This guide primarily focuses on the ``MongoCollection.bulkWrite()`` - method, which allows you to perform bulk operations on a collection. - 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 call. See the - :ref:`java-sync-client-bulk-write` section below to learn how to use the - ``MongoClient.bulkWrite()`` method. +You can perform bulk write operations by using the bulk write API in the +{+driver-short+} driver to perform multiple data changes in one call. You can +perform bulk operations at the following levels: -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. +- :ref:`Collection Level `: You can use the + ``MongoCollection.bulkWrite()`` API to perform bulk write operations on a + collection. -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 Level `: In {+mdb-server+} version + 8.0 or later, you can use the ``MongoClient.bulkWrite()`` API to perform bulk write + operations on multiple collections and databases in the same cluster. -Performing Bulk Operations --------------------------- +.. _java-sync-coll-bulk-write: + +Collection 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. +a bulk operation at the collection level, pass a ``List`` of ``WriteModel`` +documents to the ``MongoCollection.bulkWrite()`` method. A ``WriteModel`` is a model that +represents any of the write operations. The following sections show how to create and use each ``WriteModel`` document. The examples in each section use the following documents in the @@ -305,8 +306,8 @@ see the following API documentation: .. _java-sync-client-bulk-write: -Client Bulk Write Method ------------------------- +Client Bulk Write +----------------- When connecting to a deployment running {+mdb-server+} 8.0 or later, you can use the ``MongoClient.bulkWrite()`` method to write @@ -327,19 +328,19 @@ methods to represent different write operations, such as ``ClientNamespacedWrite These methods take a ``MongoNamespace`` object that defines which database and collection to write to, and a ``Document`` object that defines information about the write operation. Some methods, such as ``updateOne()`` and -``replaceOne()``, also take a ``Filters`` object that defines the filter for the operation. +``replaceOne()``, also take a ``Filters`` object that defines the subset of +documents to be updated or replaced. The following sections describe how to use the client ``bulkWrite()`` method. Insert Example ~~~~~~~~~~~~~~ -This following example shows how to use the ``bulkWrite()`` method to insert -two documents. One document is inserted into the ``people`` collection in a -database named ``db``. The other document is inserted into a collection called ``things`` -in the ``db`` database. -We use the ``MongoNamespace`` object to define the database and collection we -want each write operation to be applied to. +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 @@ -348,10 +349,21 @@ want each write operation to be applied to. List bulkOperations = new ArrayList<>(); - bulkOperations.add(ClientNamespacedWriteModel.insertOne(peopleNamespace, new Document("name", "Julia Smith"))); - bulkOperations.add(ClientNamespacedWriteModel.insertOne(thingsNamespace, new Document("object", "washing machine"))); + bulkOperations.add( + ClientNamespacedWriteModel.insertOne( + peopleNamespace, + new Document("name", "Julia Smith") + ) + ); + + bulkOperations.add( + ClientNamespacedWriteModel.insertOne( + thingsNamespace, + new Document("object", "washing machine") + ) + ); - ClientBulkWriteResult result = client.bulkWrite(bulkOperations); + ClientBulkWriteResult result = mongoClient.bulkWrite(bulkOperations); .. TODO: link documentation @@ -359,7 +371,7 @@ Replace Example ~~~~~~~~~~~~~~~ The following example shows how to use the ``bulkWrite()`` method to replace -existing documents in the ``people`` and ``things`` collections. +existing documents in the ``db.people`` and ``db.things`` collections. .. code-block:: java @@ -371,7 +383,7 @@ existing documents in the ``people`` and ``things`` collections. bulkOperations.add(ClientNamespacedWriteModel.replaceOne( peopleNamespace, Filters.eq("_id", 1), - new Document("name", "Maximus Farquaad") + new Document("name", "Frederic Hilbert") ) ); @@ -382,32 +394,34 @@ existing documents in the ``people`` and ``things`` collections. ) ); - ClientBulkWriteResult result = client.bulkWrite(bulkOperations); + ClientBulkWriteResult result = mongoClient.bulkWrite(bulkOperations); -After this example runs successfully, the document in the ``people`` collection in -which the ``_id`` field has the value of ``1`` is replaced with a new -document. The document in the ``things`` collection in which the -``_id`` field has the value of ``1`` is replaced with a new document. +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 use the ``ClientBulkWriteOptions`` interface to specify options when -running the ``bulkWrite()`` method. +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 write operations execute in the order that you specify them. However, -you can pass ``false`` to the ``ordered()`` method on the ``ClientBulkWriteOptions`` +By default, the driver performs write operations 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 will not block execution of other bulk +option, an error-producing operation does not block execution of other bulk write operations. -The following code shows how to set the ``ordered()`` method when creating an -instance of ``ClientBulkWriteOptions``. +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 @@ -417,18 +431,18 @@ instance of ``ClientBulkWriteOptions``. List bulkOperations = new ArrayList<>(); - bulkOperations.add(ClientNamespacedWriteModel.insertOne(namespace, new Document("_id", 1).append("name", "Donkey Kong))); + bulkOperations.add(ClientNamespacedWriteModel.insertOne(namespace, new Document("_id", 1).append("name", "Rudra Suraj))); - // duplicate key - bulkOperations.add(ClientNamespacedWriteModel.insertOne(namespace, new Document("_id", 1).append("name", "Mario"))); + // 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", "Princess Peach"))); + bulkOperations.add(ClientNamespacedWriteModel.insertOne(namespace, new Document("name", "Wendy Zhang"))); - ClientBulkWriteResult result = client.bulkWrite(bulkOperations, options); + ClientBulkWriteResult result = mongoClient.bulkWrite(bulkOperations, options); -Even though the write operation inserting a document with a duplicate key will -result in an error, the other operations will be executed because we have specified -the ``ordered()`` option to be ``false``. +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 @@ -454,8 +468,8 @@ There are two ways to execute the ``bulkWrite()`` method: ``MongoClient.bulkWrite()`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -In {+mdb-server+} version 8.0 and {+driver-short+} version 5.3 and later, you -can use the ``bulkWrite()`` method to perform bulk operations on multiple +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. This method uses the ``ClientNamespacedWriteModel`` and its methods @@ -465,8 +479,8 @@ This method uses the ``ClientNamespacedWriteModel`` and its methods The 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, take a look at the -:manual:`bulkWrite ` guide in the {+mdb-server+} +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 1d4eb7ccc..e61013723 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -42,10 +42,6 @@ and fixes: 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. -- A ``ClientBulkWriteOptions`` object to specify different options for how - the client bulk write API is executed. See the :ref:`java-sync-client-bulk-write-options` - section of the Client Bulk Write guide. - .. _java-version-5.2.1: What's New in 5.2.1 From 730859373a6b84e7e9e4df591ecfd2730d426d4b Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Thu, 14 Nov 2024 13:10:56 -0500 Subject: [PATCH 08/23] vale action --- .github/workflows/vale-tdbx.yml | 3 +++ 1 file changed, 3 insertions(+) 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: From c30dacd46412eff298a8d45f0f5311a1e82db983 Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Thu, 14 Nov 2024 13:30:11 -0500 Subject: [PATCH 09/23] vale --- source/fundamentals/crud/write-operations/bulk.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index 98446ceb4..2f78cadb6 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -320,7 +320,7 @@ instance of ``InsertOneModel`` represents an operation to insert one document. Similarly, the ``MongoClient.bulkWrite()`` method takes a list of ``ClientNamespacedWriteModel`` instances to represent different write operations. -However, you do not need to specify the subclass that represents the corresponding +However, you do not have to specify the subclass that represents the corresponding write operation. Instead, the ``ClientNamespacedWriteModel`` object contains different methods to represent different write operations, such as ``ClientNamespacedWriteModel.insertOne()`` or ``ClientNamespacedWriteModel.updateOne()``. From 08baf89fa5a59799065f6a48891c7c5a117fcfa3 Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Thu, 14 Nov 2024 13:46:59 -0500 Subject: [PATCH 10/23] vale? --- source/fundamentals/crud/write-operations/bulk.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index 2f78cadb6..d67ad0011 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -320,7 +320,7 @@ instance of ``InsertOneModel`` represents an operation to insert one document. Similarly, the ``MongoClient.bulkWrite()`` method takes a list of ``ClientNamespacedWriteModel`` instances to represent different write operations. -However, you do not have to specify the subclass that represents the corresponding +However, it is not necessary to specify the subclass that represents the corresponding write operation. Instead, the ``ClientNamespacedWriteModel`` object contains different methods to represent different write operations, such as ``ClientNamespacedWriteModel.insertOne()`` or ``ClientNamespacedWriteModel.updateOne()``. From fa4ff139142ffa083e4cc1886e5ad2575a2cbb5c Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Thu, 14 Nov 2024 16:23:10 -0500 Subject: [PATCH 11/23] final feedback --- .../crud/write-operations/bulk.txt | 33 ++++++++++--------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index d67ad0011..11d5daf21 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -18,21 +18,21 @@ MongoDB Java Driver. 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. The -``MongoClient`` makes a call to the database for each operation. You can reduce -the number of calls to one by using bulk write operations. +document, you can use the ``insertOne()`` and ``replaceOne()`` methods. In this +case, the ``MongoClient`` makes a call to the database for each operation. +You can reduce the number of calls to one by using bulk write operations. You can perform bulk write operations by using the bulk write API in the -{+driver-short+} driver to perform multiple data changes in one call. You can +{+driver-short+} to perform multiple data changes in one call. You can perform bulk operations at the following levels: - :ref:`Collection Level `: You can use the - ``MongoCollection.bulkWrite()`` API to perform bulk write operations on a - collection. + ``MongoCollection.bulkWrite()`` method to perform bulk write operations on a + single collection. -- :ref:`Client Level `: In {+mdb-server+} version - 8.0 or later, you can use the ``MongoClient.bulkWrite()`` API to perform bulk write - operations on multiple collections and databases in the same cluster. +- :ref:`Client Level `: When running {+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. .. _java-sync-coll-bulk-write: @@ -320,11 +320,14 @@ instance of ``InsertOneModel`` represents an operation to insert one document. Similarly, the ``MongoClient.bulkWrite()`` method takes a list of ``ClientNamespacedWriteModel`` instances to represent different write operations. -However, it is not necessary to specify the subclass that represents the corresponding -write operation. Instead, the ``ClientNamespacedWriteModel`` object contains different -methods to represent different write operations, such as ``ClientNamespacedWriteModel.insertOne()`` or +Instead of selecting a specific subclass for each write operation, the +``ClientNamespacedWriteModel`` object contains different methods to represent +write operations, such as ``ClientNamespacedWriteModel.insertOne()`` or ``ClientNamespacedWriteModel.updateOne()``. +``ClientNamespacedWriteModel`` contains the methods ``insertOne()``, ``updateOne()``, +``updateMany()``, ``replaceOne()``, ``deleteOne()``, and ``deleteMany()``. + These methods take a ``MongoNamespace`` object that defines which database and collection to write to, and a ``Document`` object that defines information about the write operation. Some methods, such as ``updateOne()`` and @@ -416,8 +419,8 @@ By default, the driver performs write operations in the order that you specify t 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 block execution of other bulk -write operations. +option, an error-producing operation does not block 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 @@ -431,7 +434,7 @@ insert multiple documents. List bulkOperations = new ArrayList<>(); - bulkOperations.add(ClientNamespacedWriteModel.insertOne(namespace, new Document("_id", 1).append("name", "Rudra Suraj))); + 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"))); From 578cb8d12b86b29740fdfff622eeac268d7ed898 Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Thu, 14 Nov 2024 16:26:03 -0500 Subject: [PATCH 12/23] consolidate --- source/fundamentals/crud/write-operations/bulk.txt | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index 11d5daf21..82be4083b 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -322,11 +322,9 @@ Similarly, the ``MongoClient.bulkWrite()`` method takes a list of ``ClientNamespacedWriteModel`` instances to represent different write operations. Instead of selecting a specific subclass for each write operation, the ``ClientNamespacedWriteModel`` object contains different methods to represent -write operations, such as ``ClientNamespacedWriteModel.insertOne()`` or -``ClientNamespacedWriteModel.updateOne()``. - -``ClientNamespacedWriteModel`` contains the methods ``insertOne()``, ``updateOne()``, -``updateMany()``, ``replaceOne()``, ``deleteOne()``, and ``deleteMany()``. +write operations. ``ClientNamespacedWriteModel`` contains the methods +``insertOne()``, ``updateOne()``, ``updateMany()``, ``replaceOne()``, +``deleteOne()``, and ``deleteMany()``. These methods take a ``MongoNamespace`` object that defines which database and collection to write to, and a ``Document`` object that defines From 1c94b5c33441345e55efa936325964f1d5a95b74 Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Thu, 14 Nov 2024 16:35:02 -0500 Subject: [PATCH 13/23] code example --- .../crud/write-operations/bulk.txt | 21 ++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index 82be4083b..9faeada56 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -432,12 +432,27 @@ insert multiple documents. List bulkOperations = new ArrayList<>(); - bulkOperations.add(ClientNamespacedWriteModel.insertOne(namespace, new Document("_id", 1).append("name", "Rudra Suraj"))); + 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("_id", 1).append("name", "Mario Bianchi") + ) + ); - bulkOperations.add(ClientNamespacedWriteModel.insertOne(namespace, new Document("name", "Wendy Zhang"))); + bulkOperations.add( + ClientNamespacedWriteModel.insertOne( + namespace, + new Document("name", "Wendy Zhang") + ) + ); ClientBulkWriteResult result = mongoClient.bulkWrite(bulkOperations, options); From ad5ea2890501f54a84856d590f5d1bc9045af673 Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Tue, 3 Dec 2024 16:45:52 -0800 Subject: [PATCH 14/23] tech feedback --- .../crud/write-operations/bulk.txt | 84 +++++++++++-------- 1 file changed, 50 insertions(+), 34 deletions(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index 9faeada56..214ee5a51 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -19,11 +19,11 @@ MongoDB Java Driver. 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. In this -case, the ``MongoClient`` makes a call to the database for each operation. -You can reduce the number of calls to one by using bulk write operations. +case, the ``MongoClient`` makes a call to the database for each operation. However, +by using bulk write operations, you can reduce the number of calls. You can perform bulk write operations by using the bulk write API in the -{+driver-short+} to perform multiple data changes in one call. You can +{+driver-short+} to define multiple data changes in one method call. You can perform bulk operations at the following levels: - :ref:`Collection Level `: You can use the @@ -320,19 +320,25 @@ instance of ``InsertOneModel`` represents an operation to insert one document. Similarly, the ``MongoClient.bulkWrite()`` method takes a list of ``ClientNamespacedWriteModel`` instances to represent different write operations. -Instead of selecting a specific subclass for each write operation, the -``ClientNamespacedWriteModel`` object contains different methods to represent -write operations. ``ClientNamespacedWriteModel`` contains the methods -``insertOne()``, ``updateOne()``, ``updateMany()``, ``replaceOne()``, -``deleteOne()``, and ``deleteMany()``. +For example, an instance of ``ClientNamespacedInsertOneModel`` represents an +operation to insert one document. + +You can construct these ``ClientNamespacedWriteModel`` instances using different +methods to represent write operations. ``ClientNamespacedWriteModel`` contains +the methods ``insertOne()``, ``updateOne()``, ``updateMany()``, ``replaceOne()``, +``deleteOne()``, and ``deleteMany()``. These methods are used to construct corresponding +write models. For example, ``ClientNamespacedWriteModel.updateOne()`` is used to +construct a ``ClientNamespacedUpdateOneModel`` instance, which represents an +update operation. These methods take a ``MongoNamespace`` object that defines which -database and collection to write to, and a ``Document`` object that defines -information about the write operation. Some methods, such as ``updateOne()`` and -``replaceOne()``, also take a ``Filters`` object that defines the subset of -documents to be updated or replaced. +database and collection to write to. Some, such as ``insertOne()``, can take a +``Document`` instance that defines information about the write operation. +Some other methods, such as ``updateOne()`` and ``replaceOne()``, take a filter +object that defines the subset of documents to be updated or replaced. -The following sections describe how to use the client ``bulkWrite()`` method. +The following sections provide examples of how to use the client ``bulkWrite()`` +method. Insert Example ~~~~~~~~~~~~~~ @@ -350,19 +356,20 @@ each write operation applies to. List bulkOperations = new ArrayList<>(); - bulkOperations.add( - ClientNamespacedWriteModel.insertOne( + ClientNamespacedInsertOneModel insertDocument1 = new ClientNamespacedWriteModel + .insertOne( peopleNamespace, new Document("name", "Julia Smith") - ) - ); + ); - bulkOperations.add( - ClientNamespacedWriteModel.insertOne( + ClientNamespacedInsertOneModel insertDocument2 = new ClientNamespacedWriteModel + .insertOne( thingsNamespace, new Document("object", "washing machine") - ) - ); + ); + + bulkOperations.add(insertDocument1); + bulkOperations.add(insertDocument2); ClientBulkWriteResult result = mongoClient.bulkWrite(bulkOperations); @@ -413,12 +420,13 @@ method to specify options when running the bulk write operations. Order of Execution Example `````````````````````````` -By default, the driver performs write operations 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 block execution of other write -operations in the call to the ``bulkWrite()`` method. +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 @@ -469,9 +477,9 @@ Summary ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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``. @@ -488,12 +496,20 @@ 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. -This method uses the ``ClientNamespacedWriteModel`` and its methods -``insertOne()``, ``updateOne()``, ``updateMany()``, ``replaceOne()``, -``deleteOne()``, and ``deleteMany()``. +To perform a client bulk operation, you create an pass a list of +``ClientNamespacedWriteModel`` instances to this method. + +There are six subtypes of ``ClientNamespacedWriteModel``: ``ClientNamespacedInsertOneModel``, +``ClientNamespacedUpdateOneModel``, ``ClientNamespacedUpdateManyModel``, +``ClientNamespacedReplaceOneModel``, ``ClientNamespacedDeleteOneModel``, and +``ClientNamespacedDeleteManyModel``. To construct these write models, you can +use the ``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 method can also take a ``ClientBulkWriteOptions`` object to specify different -options for how the command is executed. +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+} From d9a33d9a1a2c4744adb48a44788389962ee1deb3 Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Tue, 3 Dec 2024 18:10:50 -0800 Subject: [PATCH 15/23] reduce info --- source/fundamentals/crud/write-operations/bulk.txt | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index 214ee5a51..05b8cdb9f 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -499,11 +499,9 @@ 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``: ``ClientNamespacedInsertOneModel``, -``ClientNamespacedUpdateOneModel``, ``ClientNamespacedUpdateManyModel``, -``ClientNamespacedReplaceOneModel``, ``ClientNamespacedDeleteOneModel``, and -``ClientNamespacedDeleteManyModel``. To construct these write models, you can -use the ``ClientNamespacedWriteModel`` methods ``insertOne()``, ``updateOne()``, +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. From 02b17208b96c0bfeb4da1f827d07c3d20007a384 Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Tue, 10 Dec 2024 15:39:25 -0500 Subject: [PATCH 16/23] feedback --- .../crud/write-operations/bulk.txt | 39 ++++++++++++------- 1 file changed, 26 insertions(+), 13 deletions(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index 05b8cdb9f..16f8d909b 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -10,6 +10,9 @@ Bulk Operations :depth: 2 :class: singlecol +.. meta:: + :keywords: insert, update, replace, code example, efficiency + Overview -------- @@ -19,28 +22,37 @@ MongoDB Java Driver. 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. In this -case, the ``MongoClient`` makes a call to the database for each operation. However, -by using bulk write operations, you can reduce the number of calls. +case, the ``MongoClient`` makes a call to the database for each operation. -You can perform bulk write operations by using the bulk write API in the -{+driver-short+} to define multiple data changes in one method call. You can -perform bulk operations at the following levels: +Generally, you can reduce the number of calls to the database by using bulk write +operations. You can perform bulk write operations at the following levels: - :ref:`Collection Level `: You can use the ``MongoCollection.bulkWrite()`` method to perform bulk write operations on a - single collection. + single collection. This method groups write operations together by the kind + of operation. For example, ``MongoCollection.bulkWrite()`` puts multiple insert + operations, including ``insertOne()`` and ``insertMany()``, in the same call, + but will make two calls to the database for an insert operation and a replace + operation. - :ref:`Client Level `: When running {+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 groups multiple kinds of write operations into one call. .. _java-sync-coll-bulk-write: Collection Bulk Write --------------------- -Bulk operations consist of a large number of write operations. To perform -a bulk operation at the collection level, pass a ``List`` of ``WriteModel`` +Bulk operations consist of a large number of write operations. The +``MongoCollection.bulkWrite()`` method splits operations of different kinds into +different batches. For example, when the method is passed an ``insertOne()``, +``insertMany()``, and ``replaceOne()`` operation, it will split the insert operations +into one batch and the replace operation into another. During this process, +the client may reorder operations for efficiency. + +To perform a bulk operation at the collection level, pass a ``List`` of ``WriteModel`` documents to the ``MongoCollection.bulkWrite()`` method. A ``WriteModel`` is a model that represents any of the write operations. @@ -221,14 +233,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 @@ -264,7 +276,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 @@ -311,7 +323,8 @@ 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. +to multiple databases and collections in the same cluster. The ``MongoClient.bulkWrite()`` +method does not split different kinds of operations into different batches. In the examples in preceding sections of this page, the ``MongoCollection.bulkWrite()`` method takes a list of ``WriteModel`` instances in which the specified subclass of From ef63a45594fce8124b4de0f47a84d68da235faef Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Tue, 10 Dec 2024 15:50:14 -0500 Subject: [PATCH 17/23] vale fix --- source/fundamentals/crud/write-operations/bulk.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index 16f8d909b..42f571357 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -45,7 +45,7 @@ operations. You can perform bulk write operations at the following levels: Collection Bulk Write --------------------- -Bulk operations consist of a large number of write operations. The +Bulk operations consist of many write operations. The ``MongoCollection.bulkWrite()`` method splits operations of different kinds into different batches. For example, when the method is passed an ``insertOne()``, ``insertMany()``, and ``replaceOne()`` operation, it will split the insert operations From 1cfd45111f22d2a4b5ff8998b0e57bccf58a025b Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Thu, 12 Dec 2024 16:03:55 -0500 Subject: [PATCH 18/23] feedback --- .../crud/write-operations/bulk.txt | 48 ++++++++++++------- 1 file changed, 30 insertions(+), 18 deletions(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index 42f571357..292786330 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -30,10 +30,9 @@ operations. You can perform bulk write operations at the following levels: - :ref:`Collection Level `: You can use the ``MongoCollection.bulkWrite()`` method to perform bulk write operations on a single collection. This method groups write operations together by the kind - of operation. For example, ``MongoCollection.bulkWrite()`` puts multiple insert - operations, including ``insertOne()`` and ``insertMany()``, in the same call, - but will make two calls to the database for an insert operation and a replace - operation. + of operation. For example, ``MongoCollection.bulkWrite()`` puts multiple update + operations in the same call, but makes two calls to the database for an insert + operation and a replace operation. - :ref:`Client Level `: When running {+mdb-server+} version 8.0 or later, you can use the ``MongoClient.bulkWrite()`` method to perform @@ -45,17 +44,18 @@ operations. You can perform bulk write operations at the following levels: Collection Bulk Write --------------------- -Bulk operations consist of many write operations. The -``MongoCollection.bulkWrite()`` method splits operations of different kinds into -different batches. For example, when the method is passed an ``insertOne()``, -``insertMany()``, and ``replaceOne()`` operation, it will split the insert operations -into one batch and the replace operation into another. During this process, -the client may reorder operations for efficiency. - -To perform a bulk operation at the collection level, pass a ``List`` of ``WriteModel`` -documents to the ``MongoCollection.bulkWrite()`` method. A ``WriteModel`` is a model that +Bulk operations consist of many write operations. To perform a bulk operation +at the collection level, pass a ``List`` of ``WriteModel`` documents to the +``MongoCollection.bulkWrite()`` method. A ``WriteModel`` is a model that represents any of the write operations. +The ``MongoCollection.bulkWrite()`` method splits operations of different kinds into +different batches. For example, when you pass ``DeleteOneModel``, +``DeleteManyModel``, and ``ReplaceOneModel`` operations to the method, the method +splits the delete operations into one batch and the replace operation +into another. During this process, the client might reorder operations for +efficiency if the bulk operation is not ordered. + The following sections show how to create and use each ``WriteModel`` document. The examples in each section use the following documents in the ``people`` collection: @@ -336,11 +336,23 @@ list of ``ClientNamespacedWriteModel`` instances to represent different write op For example, an instance of ``ClientNamespacedInsertOneModel`` represents an operation to insert one document. -You can construct these ``ClientNamespacedWriteModel`` instances using different -methods to represent write operations. ``ClientNamespacedWriteModel`` contains -the methods ``insertOne()``, ``updateOne()``, ``updateMany()``, ``replaceOne()``, -``deleteOne()``, and ``deleteMany()``. These methods are used to construct corresponding -write models. For example, ``ClientNamespacedWriteModel.updateOne()`` is used to +You can construct instances of ``ClientNamespacedWriteModel`` using the following +methods: + +- ``insertOne()`` + +- ``updateOne()`` + +- ``updateMany()`` + +- ``replaceOne()`` + +- ``deleteOne()`` + +- ``deleteMany()`` + +These methods are used to construct corresponding write models. +For example, ``ClientNamespacedWriteModel.updateOne()`` is used to construct a ``ClientNamespacedUpdateOneModel`` instance, which represents an update operation. From 7110a7f2859cec7c0c3d279a5f8e3d5adee1fc39 Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Tue, 17 Dec 2024 16:24:44 -0800 Subject: [PATCH 19/23] Feedback --- .../crud/write-operations/bulk.txt | 141 ++++++++++++------ 1 file changed, 97 insertions(+), 44 deletions(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index 292786330..ab6876509 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -21,40 +21,45 @@ MongoDB Java Driver. 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. In this -case, the ``MongoClient`` makes a call to the database for each operation. +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. -Generally, you can reduce the number of calls to the database by using bulk write -operations. You can perform bulk write operations at the following levels: +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 Level `: You can use the +- :ref:`Collection `: You can use the ``MongoCollection.bulkWrite()`` method to perform bulk write operations on a single collection. This method groups write operations together by the kind of operation. For example, ``MongoCollection.bulkWrite()`` puts multiple update - operations in the same call, but makes two calls to the database for an insert + operations in one call, but makes two separate calls to the database for an insert operation and a replace operation. -- :ref:`Client Level `: When running {+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 groups multiple kinds of write operations into one call. +- :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. .. _java-sync-coll-bulk-write: Collection Bulk Write --------------------- -Bulk operations consist of many write operations. To perform a bulk operation -at the collection level, pass a ``List`` of ``WriteModel`` documents to the -``MongoCollection.bulkWrite()`` method. A ``WriteModel`` is a model that -represents any of the write operations. +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 splits operations of different kinds into -different batches. For example, when you pass ``DeleteOneModel``, -``DeleteManyModel``, and ``ReplaceOneModel`` operations to the method, the method -splits the delete operations into one batch and the replace operation -into another. During this process, the client might reorder operations for -efficiency if the bulk operation is not ordered. +The ``MongoCollection.bulkWrite()`` method performs each kind of write +operations in a separate call. For example, when you pass ``DeleteOneModel``, +``DeleteManyModel``, and ``ReplaceOneModel`` objects to the method, it creates +two calls: one for the delete operations and one for the replace operation. + +.. note:: + + When the client splits operations into 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 @@ -324,43 +329,91 @@ 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 does not split different kinds of operations into different batches. +method performs all write operations in a single call. -In the examples in preceding sections of this page, the ``MongoCollection.bulkWrite()`` method -takes a list of ``WriteModel`` instances in which the specified subclass of -``WriteModel`` represents the corresponding write operation. For example, an -instance of ``InsertOneModel`` represents an operation to insert one document. - -Similarly, the ``MongoClient.bulkWrite()`` method takes a +The ``MongoClient.bulkWrite()`` method takes a list of ``ClientNamespacedWriteModel`` instances to represent different write operations. For example, an instance of ``ClientNamespacedInsertOneModel`` represents an operation to insert one document. -You can construct instances of ``ClientNamespacedWriteModel`` using the following -methods: +You can construct instances of the ``ClientNamespacedWriteModel`` interface by using +instance methods described in the table below. These methods take a +``MongoNamespace`` object that defines which database and collection to write to. + +.. list-table:: + :header-rows: 1 + + * - Instance Method + - Class Constructed + - Parameters + - Operation Description + + * - ``insertOne()`` + - ``ClientNamespacedInsertOneModel`` + - ``namespace``: defines which database and collection to write to + + ``document``: defines the document to insert + - Creates a model to insert a document into the ``namespace``. + + * - ``updateOne()`` + - ``ClientNamespacedInsertOneModel`` + - ``namespace``: defines which database and collection to write to + + ``filter``: defines filter that selects which document to update + + ``update``: defines update to apply to matching document + + ``updatePipeline``: defines update pipeline to apply to matching document + + ``options``: (optional) defines options to apply when updating document + + One of ``update`` or ``updatePipeline`` must be specified. + - Creates a model to update at most one document in the ``namespace`` + that matches ``filter``. + + * - ``updateMany()`` + - ``ClientNamespacedUpdateManyModel`` + - ``namespace``: defines which database and collection to write to + + ``filter``: defines filter that selects which documents to update + + ``update``: defines update to apply to matching documents + + ``updatePipeline``: defines update pipeline to apply to matching documents + + ``options``: (optional) defines options to apply when updating documents + + One of ``update`` or ``updatePipeline`` must be specified. + - Updates all documents in the ``namespace`` that match ``filter``. + + * - ``replaceOne()`` + - ``ClientNamespacedReplaceOneModel`` + - ``namespace``: defines which database and collection to write to + + ``filter``: defines filter that selects which document to replace -- ``insertOne()`` + ``replacement``: defines replacement document -- ``updateOne()`` + ``options``: (optional) defines options to apply when replacing documents + - Replaces at most one document in the ``namespace`` that matches ``filter``. -- ``updateMany()`` + * - ``deleteOne()`` + - ``ClientNamespacedDeleteOneModel`` + - ``namespace``: defines which database and collection to write to -- ``replaceOne()`` + ``filter``: defines filter that selects which document to delete -- ``deleteOne()`` + ``option``: (optional) defines options to apply when deleting document + - Deletes at most one document in the ``namespace`` that matches ``filter``. -- ``deleteMany()`` + * - ``deleteMany()`` + - ``ClientNamespacedDeleteManyModel`` + - ``namespace``: defines which database and collection to write to -These methods are used to construct corresponding write models. -For example, ``ClientNamespacedWriteModel.updateOne()`` is used to -construct a ``ClientNamespacedUpdateOneModel`` instance, which represents an -update operation. + ``filter``: defines filter that selects which documents to delete -These methods take a ``MongoNamespace`` object that defines which -database and collection to write to. Some, such as ``insertOne()``, can take a -``Document`` instance that defines information about the write operation. -Some other methods, such as ``updateOne()`` and ``replaceOne()``, take a filter -object that defines the subset of documents to be updated or replaced. + ``option``: (optional) defines options to apply when deleting documents + - Deletes all documents in the ``namespace`` that match ``filter``. The following sections provide examples of how to use the client ``bulkWrite()`` method. From 68e6074041723d862e72571250fe82d2174af6d2 Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Tue, 17 Dec 2024 16:46:58 -0800 Subject: [PATCH 20/23] table --- .../crud/write-operations/bulk.txt | 55 ++++++++++--------- 1 file changed, 30 insertions(+), 25 deletions(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index ab6876509..0c24181a0 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -337,26 +337,29 @@ For example, an instance of ``ClientNamespacedInsertOneModel`` represents an operation to insert one document. You can construct instances of the ``ClientNamespacedWriteModel`` interface by using -instance methods described in the table below. These methods take a +instance methods. The models and their corresponding instance methods are described +in the table below. These methods take a ``MongoNamespace`` object that defines which database and collection to write to. .. list-table:: :header-rows: 1 - * - Instance Method - - Class Constructed + * - Model + - Instance Method + - Description - Parameters - - Operation Description - * - ``insertOne()`` - - ``ClientNamespacedInsertOneModel`` - - ``namespace``: defines which database and collection to write to + * - ``ClientNamespacedInsertOneModel`` + - ``insertOne()`` + - Creates a model to insert a document into the ``namespace``. + - ``namespace``: defines which database and collection to write to - ``document``: defines the document to insert - - Creates a model to insert a document into the ``namespace``. + ``document``: defines the document to insert - * - ``updateOne()`` - - ``ClientNamespacedInsertOneModel`` + * - ``ClientNamespacedUpdateOneModel`` + - ``updateOne()`` + - Creates a model to update at most one document in the ``namespace`` + that matches ``filter``. - ``namespace``: defines which database and collection to write to ``filter``: defines filter that selects which document to update @@ -368,11 +371,11 @@ instance methods described in the table below. These methods take a ``options``: (optional) defines options to apply when updating document One of ``update`` or ``updatePipeline`` must be specified. - - Creates a model to update at most one document in the ``namespace`` - that matches ``filter``. - * - ``updateMany()`` - - ``ClientNamespacedUpdateManyModel`` + * - ``ClientNamespacedUpdateManyModel`` + - ``updateMany()`` + - Creates a model to update all documents in the ``namespace`` that match + ``filter``. - ``namespace``: defines which database and collection to write to ``filter``: defines filter that selects which documents to update @@ -384,10 +387,11 @@ instance methods described in the table below. These methods take a ``options``: (optional) defines options to apply when updating documents One of ``update`` or ``updatePipeline`` must be specified. - - Updates all documents in the ``namespace`` that match ``filter``. - * - ``replaceOne()`` - - ``ClientNamespacedReplaceOneModel`` + * - ``ClientNamespacedReplaceOneModel`` + - ``replaceOne()`` + - Creates a model to replace at most one document in the ``namespace`` that + matches ``filter``. - ``namespace``: defines which database and collection to write to ``filter``: defines filter that selects which document to replace @@ -395,25 +399,26 @@ instance methods described in the table below. These methods take a ``replacement``: defines replacement document ``options``: (optional) defines options to apply when replacing documents - - Replaces at most one document in the ``namespace`` that matches ``filter``. - * - ``deleteOne()`` - - ``ClientNamespacedDeleteOneModel`` + * - ``ClientNamespacedDeleteOneModel`` + - ``deleteOne()`` + - Creates a model to delete at most one document in the ``namespace`` that + matches ``filter``. - ``namespace``: defines which database and collection to write to ``filter``: defines filter that selects which document to delete ``option``: (optional) defines options to apply when deleting document - - Deletes at most one document in the ``namespace`` that matches ``filter``. - * - ``deleteMany()`` - - ``ClientNamespacedDeleteManyModel`` + * - ``ClientNamespacedDeleteManyModel`` + - ``deleteMany()`` + - Creates a model to delete all documents in the ``namespace`` that match + ``filter``. - ``namespace``: defines which database and collection to write to ``filter``: defines filter that selects which documents to delete ``option``: (optional) defines options to apply when deleting documents - - Deletes all documents in the ``namespace`` that match ``filter``. The following sections provide examples of how to use the client ``bulkWrite()`` method. From 99344755c39bae302cad3b9f26aaa29ded17a457 Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Tue, 17 Dec 2024 17:04:49 -0800 Subject: [PATCH 21/23] clean --- source/fundamentals/crud/write-operations/bulk.txt | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index 0c24181a0..3be748421 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -333,13 +333,13 @@ method performs all write operations in a single call. The ``MongoClient.bulkWrite()`` method takes a list of ``ClientNamespacedWriteModel`` instances to represent different write operations. -For example, an instance of ``ClientNamespacedInsertOneModel`` represents an -operation to insert one document. - You can construct instances of the ``ClientNamespacedWriteModel`` interface by using -instance methods. The models and their corresponding instance methods are described -in the table below. These methods take a -``MongoNamespace`` object that defines which database and collection to write to. +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 From f43f5c99cac48eb525f4fc56052603fbefb8d447 Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Tue, 17 Dec 2024 17:09:26 -0800 Subject: [PATCH 22/23] fix --- source/fundamentals/crud/write-operations/bulk.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index 3be748421..7ddf7269b 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -29,8 +29,8 @@ fewer database calls. You can perform bulk write operations at the following lev - :ref:`Collection `: You can use the ``MongoCollection.bulkWrite()`` method to perform bulk write operations on a - single collection. This method groups write operations together by the kind - of operation. For example, ``MongoCollection.bulkWrite()`` puts multiple update + 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. From 605cf7db14509e186647139de924ad1f0be83a1b Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Wed, 18 Dec 2024 14:19:36 -0800 Subject: [PATCH 23/23] final feedback --- .../crud/write-operations/bulk.txt | 66 ++++++++++--------- 1 file changed, 34 insertions(+), 32 deletions(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index 7ddf7269b..959d00468 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -51,15 +51,15 @@ 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 -operations in a separate call. For example, when you pass ``DeleteOneModel``, -``DeleteManyModel``, and ``ReplaceOneModel`` objects to the method, it creates +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 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. + 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 @@ -352,73 +352,75 @@ in the table below. * - ``ClientNamespacedInsertOneModel`` - ``insertOne()`` - Creates a model to insert a document into the ``namespace``. - - ``namespace``: defines which database and collection to write to + - ``namespace``: Database and collection to write to - ``document``: defines the document to insert + ``document``: Document to insert * - ``ClientNamespacedUpdateOneModel`` - ``updateOne()`` - - Creates a model to update at most one document in the ``namespace`` + - Creates a model to update the first document in the ``namespace`` that matches ``filter``. - - ``namespace``: defines which database and collection to write to + - ``namespace``: Database and collection to write to - ``filter``: defines filter that selects which document to update + ``filter``: Filter that selects which document to update - ``update``: defines update to apply to matching document + ``update``: Update to apply to matching document - ``updatePipeline``: defines update pipeline to apply to matching document + ``updatePipeline``: Update pipeline to apply to matching document - ``options``: (optional) defines options to apply when updating document + ``options``: (optional) Options to apply when updating document - One of ``update`` or ``updatePipeline`` must be specified. + 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``: defines which database and collection to write to + - ``namespace``: Database and collection to write to - ``filter``: defines filter that selects which documents to update + ``filter``: Filter that selects which documents to update - ``update``: defines update to apply to matching documents + ``update``: Update to apply to matching documents - ``updatePipeline``: defines update pipeline to apply to matching documents + ``updatePipeline``: Update pipeline to apply to matching documents - ``options``: (optional) defines options to apply when updating documents + ``options``: (optional) Options to apply when updating documents - One of ``update`` or ``updatePipeline`` must be specified. + You must pass a value for either the ``update`` or ``updatePipeline`` + parameter. * - ``ClientNamespacedReplaceOneModel`` - ``replaceOne()`` - - Creates a model to replace at most one document in the ``namespace`` that + - Creates a model to replace the first document in the ``namespace`` that matches ``filter``. - - ``namespace``: defines which database and collection to write to + - ``namespace``: Database and collection to write to - ``filter``: defines filter that selects which document to replace + ``filter``: Filter that selects which document to replace - ``replacement``: defines replacement document + ``replacement``: Replacement document - ``options``: (optional) defines options to apply when replacing documents + ``options``: (optional) Options to apply when replacing documents * - ``ClientNamespacedDeleteOneModel`` - ``deleteOne()`` - - Creates a model to delete at most one document in the ``namespace`` that + - Creates a model to delete the first document in the ``namespace`` that matches ``filter``. - - ``namespace``: defines which database and collection to write to + - ``namespace``: Database and collection to write to - ``filter``: defines filter that selects which document to delete + ``filter``: Filter that selects which document to delete - ``option``: (optional) defines options to apply when deleting document + ``option``: (optional) Options to apply when deleting document * - ``ClientNamespacedDeleteManyModel`` - ``deleteMany()`` - Creates a model to delete all documents in the ``namespace`` that match ``filter``. - - ``namespace``: defines which database and collection to write to + - ``namespace``: Database and collection to write to - ``filter``: defines filter that selects which documents to delete + ``filter``: Filter that selects which documents to delete - ``option``: (optional) defines options to apply when deleting documents + ``option``: (optional) Options to apply when deleting documents The following sections provide examples of how to use the client ``bulkWrite()`` method.