Skip to content

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
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
151 changes: 150 additions & 1 deletion source/fundamentals/crud/write-operations/bulk.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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

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,
update multiple documents, and delete one document in your collection,
Expand Down Expand Up @@ -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:

- `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>`__
Expand Down Expand Up @@ -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:

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 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 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
document information. 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.

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
We use the ``MongoNamespace`` object to define the database and collection we
want each write operation to be applied to.
The example defines ``MongoNamespace`` instances to define the databases and collections
to which each write operation applies.

Copy link
Contributor

Choose a reason for hiding this comment

The 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.

.. 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.

.. 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")
),
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.

Bulk Write Options
~~~~~~~~~~~~~~~~~~

Similarly to the :ref:`orderOfExecution` section above, you can use the
``ClientBulkWriteOptions`` object to execute the new ``bulkWrite()`` method
with options.

Order of Execution Example
``````````````````````````

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.

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"))
),
options);

.. TODO: link documentation

Summary
-------

``MongoCollection.bulkWrite()``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To perform a bulk operation, you create and pass a list of
``WriteModel`` documents to the ``bulkWrite()`` method.

Expand All @@ -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
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?
11 changes: 11 additions & 0 deletions source/whats-new.txt
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ What's New

Learn what's new in:

* :ref:`Version 5.3 <java-version-5.3>`
* :ref:`Version 5.2.1 <java-version-5.2.1>`
* :ref:`Version 5.2 <java-version-5.2>`
* :ref:`Version 5.1.3 <java-version-5.1.3>`
Expand All @@ -29,6 +30,16 @@ Learn what's new in:
* :ref:`Version 4.11 <version-4.11>`
* :ref:`Version 4.10 <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 <improved-bulk-write>` 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
Expand Down
Loading