-
Notifications
You must be signed in to change notification settings - Fork 43
DOCSP-41769: Improved bulk write API #590
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
mayaraman19
merged 24 commits into
mongodb:master
from
mayaraman19:DOCSP-41769-improved-bulk-write
Dec 18, 2024
Merged
Changes from 3 commits
Commits
Show all changes
24 commits
Select commit
Hold shift + click to select a range
72b9e73
initial checkpoint
mayaraman19 09d5786
Initial full pass
mayaraman19 161ffec
first pass edits
mayaraman19 9d37fac
feedback initial pass
mayaraman19 5e577ba
finished feedback
mayaraman19 78d26c0
manual
mayaraman19 db24b1e
feedback part 2
mayaraman19 56413a0
Merge branch 'master' of https://github.com/mongodb/docs-java into DO…
mayaraman19 7308593
vale action
mayaraman19 c30dacd
vale
mayaraman19 08baf89
vale?
mayaraman19 fa4ff13
final feedback
mayaraman19 578cb8d
consolidate
mayaraman19 1c94b5c
code example
mayaraman19 ad5ea28
tech feedback
mayaraman19 d9a33d9
reduce info
mayaraman19 02b1720
feedback
mayaraman19 ef63a45
vale fix
mayaraman19 1cfd451
feedback
mayaraman19 7110a7f
Feedback
mayaraman19 68e6074
table
mayaraman19 9934475
clean
mayaraman19 f43f5c9
fix
mayaraman19 605cf7d
final feedback
mayaraman19 File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change | ||||||||
---|---|---|---|---|---|---|---|---|---|---|
|
@@ -16,6 +16,14 @@ Overview | |||||||||
In this guide, you can learn how to use bulk operations in the | ||||||||||
MongoDB Java Driver. | ||||||||||
|
||||||||||
.. note:: Improved Bulk Write Commands | ||||||||||
mayaraman19 marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
|
||||||||||
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. | ||||||||||
mayaraman19 marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
|
||||||||||
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 +52,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: | ||||||||||
mayaraman19 marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
|
||||||||||
- `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,9 +301,128 @@ 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: | ||||||||||
mayaraman19 marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
|
||||||||||
Improved Bulk Write Command | ||||||||||
mayaraman19 marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
--------------------------- | ||||||||||
|
||||||||||
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. | ||||||||||
mayaraman19 marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
|
||||||||||
In the previous examples on this page, the ``bulkWrite()`` method takes a list | ||||||||||
mayaraman19 marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
of ``WriteModel`` documents in which the specified subclass of ``WriteModel`` | ||||||||||
mayaraman19 marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
represents the corresponding write operation. For example, ``InsertOneModel`` | ||||||||||
represents inserting one document. | ||||||||||
mayaraman19 marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
|
||||||||||
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()``. | ||||||||||
mayaraman19 marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
|
||||||||||
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()``, | ||||||||||
mayaraman19 marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
also take a ``Filters`` object that defines the filter for the operation. | ||||||||||
|
||||||||||
The following sections describe how to use the new ``bulkWrite()`` method. | ||||||||||
mayaraman19 marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
|
||||||||||
Insert Example | ||||||||||
~~~~~~~~~~~~~~ | ||||||||||
|
||||||||||
The following example shows how to use the new ``bulkWrite()`` method to insert | ||||||||||
mayaraman19 marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
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. | ||||||||||
mayaraman19 marked this conversation as resolved.
Show resolved
Hide resolved
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. |
||||||||||
|
||||||||||
.. code-block:: java | ||||||||||
|
||||||||||
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")) | ||||||||||
)); | ||||||||||
|
||||||||||
After this example is executed, the ``people`` collection holds a | ||||||||||
``{ "name": "Julia Smith" }`` document and the ``things`` collection holds | ||||||||||
a ``{ "object": "washing machine" }`` document. | ||||||||||
mayaraman19 marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
|
||||||||||
.. TODO: link documentation | ||||||||||
rustagir marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
|
||||||||||
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. | ||||||||||
mayaraman19 marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
|
||||||||||
.. code-block:: java | ||||||||||
|
||||||||||
MongoNamespace peopleNamespace = new MongoNamespace("db", "people"); | ||||||||||
MongoNamespace thingsNamespace = new MongoNamespace("db", "things"); | ||||||||||
|
||||||||||
ClientBulkWriteResult result = client.bulkWrite(List<>( | ||||||||||
ClientNamespacedWriteModel.replaceOne( | ||||||||||
peopleNamespace, | ||||||||||
Filters.eq("_id", 1), | ||||||||||
new Document("name", "Maximus Farquaad") | ||||||||||
mayaraman19 marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
), | ||||||||||
ClientNamespacedWriteModel.replaceOne( | ||||||||||
thingsNamespace, | ||||||||||
Filters.eq("_id", 1), | ||||||||||
new Document("object", "potato") | ||||||||||
) | ||||||||||
)); | ||||||||||
|
||||||||||
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. | ||||||||||
mayaraman19 marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
|
||||||||||
Bulk Write Options | ||||||||||
~~~~~~~~~~~~~~~~~~ | ||||||||||
|
||||||||||
Similarly to the :ref:`orderOfExecution` section above, you can use the | ||||||||||
``ClientBulkWriteOptions`` object to execute the new ``bulkWrite()`` method | ||||||||||
with options. | ||||||||||
mayaraman19 marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
|
||||||||||
Order of Execution Example | ||||||||||
`````````````````````````` | ||||||||||
rustagir marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
|
||||||||||
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. | ||||||||||
mayaraman19 marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
|
||||||||||
The following code shows how to use the ``ordered()`` method on the | ||||||||||
``ClientBulkWriteOptions`` object. | ||||||||||
mayaraman19 marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
|
||||||||||
.. 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")) | ||||||||||
mayaraman19 marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
), | ||||||||||
options); | ||||||||||
mayaraman19 marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
|
||||||||||
.. TODO: link documentation | ||||||||||
|
||||||||||
Summary | ||||||||||
------- | ||||||||||
|
||||||||||
``MongoCollection.bulkWrite()`` | ||||||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||||||||||
|
||||||||||
To perform a bulk operation, you create and pass a list of | ||||||||||
``WriteModel`` documents to the ``bulkWrite()`` method. | ||||||||||
|
||||||||||
|
@@ -308,3 +435,25 @@ There are two ways to execute the ``bulkWrite()`` method: | |||||||||
- Ordered, which performs the bulk operations in order until an error occurs, if any | ||||||||||
- Unordered, which performs all the bulk operations in any order and reports errors | ||||||||||
at the end, if any | ||||||||||
|
||||||||||
``MongoClient.bulkWrite()`` | ||||||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||||||||||
|
||||||||||
In {+mdb-server+} version 8.0 and {+driver-short+} version 5.3 and later, you | ||||||||||
mayaraman19 marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
can use the ``bulkWrite()`` method to perform bulk operations on multiple | ||||||||||
mayaraman19 marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
databases and collections at once. | ||||||||||
|
||||||||||
This method uses the ``ClientNamespacedWriteModel`` and its methods | ||||||||||
``insertOne()``, ``updateOne()``, ``updateMany()``, ``replaceOne()``, | ||||||||||
``deleteOne()``, and ``deleteMany()``. | ||||||||||
mayaraman19 marked this conversation as resolved.
Show resolved
Hide resolved
stIncMale marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
|
||||||||||
The method can also take a ``ClientBulkWriteOptions`` object to specify different | ||||||||||
options for how the command is executed. | ||||||||||
|
||||||||||
.. TODO: Add API Documentation | ||||||||||
mayaraman19 marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
|
||||||||||
.. 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? |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.