Skip to content

DOCSP-31089: Improve bulk operation examples #438

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.

Sign up for GitHub

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 6 commits into from
Sep 13, 2023
Merged

DOCSP-31089: Improve bulk operation examples #438

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
e67af2d
DOCSP-31089: Improve bulk operation examples
norareidy Sep 12, 2023
dc25f09
fixing formatting
norareidy Sep 12, 2023
44aa2a7
addressing vale errors
norareidy Sep 12, 2023
107ef4b
review feedback
norareidy Sep 12, 2023
8403eda
fixing supporting code
norareidy Sep 13, 2023
0af0d9f
code formatting
norareidy Sep 13, 2023
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
59 changes: 33 additions & 26 deletions source/fundamentals/crud/write-operations/bulk.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ MongoDB Java Driver.
To perform a create, replace, update, or delete operation,
use its corresponding method. For example, to insert one document,
update multiple documents, and delete one document in your collection,
use the ``insertOne()``, ``updateMany()`` and ``deleteOne()`` methods.
use the ``insertOne()``, ``updateMany()`` and ``deleteOne()`` methods.

The ``MongoClient`` performs these operations by making a call for each
operation to the database. You can reduce the number of calls to the
Expand All @@ -31,18 +31,19 @@ Performing Bulk Operations
--------------------------

Bulk operations consist of a large number of write operations. To perform
a bulk operation, pass a ``List`` of ``WriteModel`` documents to the
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.

The following sections show how to create and use each ``WriteModel``
document. The examples in each section contain the following documents
in a collection:
document. The examples in each section use the following documents in the
``people`` collection:

.. code-block:: json

{ "_id": 1 }
{ "_id": 2 }
{ "_id": 1, "name": "Karen Sandoval", "age": 31 }
{ "_id": 2, "name": "William Chin", "age": 54 }
{ "_id": 8, "name": "Shayla Ray", "age": 20 }

For more information about the methods and classes mentioned in this section,
see the following API Documentation:
Expand All @@ -62,7 +63,7 @@ Example
```````

The following example creates an ``InsertOneModel`` for two documents
where the ``_id`` values are "3" and "4":
describing people:

.. literalinclude:: /includes/fundamentals/code-snippets/BulkWrite.java
:language: java
Expand All @@ -77,7 +78,7 @@ where the ``_id`` values are "3" and "4":
collection. Instead, the method throws a ``MongoBulkWriteException``.

The following example tries to insert two documents where the ``_id`` is
"1" and "3":
``1`` and ``3``:

.. literalinclude:: /includes/fundamentals/code-snippets/BulkWrite.java
:language: java
Expand All @@ -90,12 +91,12 @@ where the ``_id`` values are "3" and "4":
.. code-block:: shell
:copyable: false

A MongoBulkWriteException occurred with the following message:
A MongoBulkWriteException occurred with the following message:
Bulk write operation error on server sample-shard-00-02.pw0q4.mongodb.net:27017.
Write errors: [BulkWriteError{index=0, code=11000, message='E11000 duplicate key
error collection: crudOps.bulkWrite index: _id_ dup key: { _id: 1 }', details={}}].

To see why the document with the ``_id`` of "3" didn't insert, see
To see why the document with the ``_id`` of ``3`` didn't insert, see
the :ref:`Order of Execution <orderOfExecution>` section.

For more information about the methods and classes mentioned in this section,
Expand All @@ -121,8 +122,8 @@ Example
```````

The following example creates a ``ReplaceOneModel`` to
replace a document where the ``_id`` is "1" with a document that
contains an additional field:
replace a document where the ``_id`` is ``1`` with a document that
contains an added ``location`` field:

.. literalinclude:: /includes/fundamentals/code-snippets/BulkWrite.java
:language: java
Expand Down Expand Up @@ -158,8 +159,7 @@ Example
```````

The following example creates an ``UpdateOneModel`` to update
a document where the ``_id`` is "2" to a document that
contains an additional field:
the ``age`` field in a document where the ``_id`` is ``2``:

.. literalinclude:: /includes/fundamentals/code-snippets/BulkWrite.java
:language: java
Expand Down Expand Up @@ -195,7 +195,7 @@ Example
```````

The following example creates a ``DeleteOneModel`` to delete
a document where the ``_id`` is "1":
a document where the ``_id`` is ``1``:

.. literalinclude:: /includes/fundamentals/code-snippets/BulkWrite.java
:language: java
Expand All @@ -214,9 +214,9 @@ see the following API Documentation:
Order of Execution
------------------

The ``bulkWrite()`` method accepts an optional ``BulkWriteOptions`` as
a second parameter to specify if you want to execute the bulk operations
as ordered or unordered.
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 Execution
~~~~~~~~~~~~~~~~~
Expand All @@ -230,10 +230,13 @@ Example

The following example performs these bulk operations:

- An insert operation for a document where the ``_id`` is "3"
- A replace operation for a document where the ``_id`` is "1" with a document that contains an additional field
- An update operation for a document where the ``_id`` is "3" to a document that contains an additional field
- A delete operation for all documents that contain the field ``x`` with the value "2"
- An operation that inserts a document with a ``name`` value of ``"Zaynab Omar"`` and an
``age`` value of ``37``
- An operation that replaces the document where the ``_id`` is ``1`` with a new document
that contains the ``location`` field
- An operation that updates the document with a ``name`` value of ``"Zaynab Omar"`` and
changes the ``name`` to ``"Zaynab Hassan"``
- An operation that deletes all documents where the ``age`` value is greater than ``50``

.. literalinclude:: /includes/fundamentals/code-snippets/BulkWrite.java
:language: java
Expand All @@ -247,7 +250,9 @@ document:
.. code-block:: json
:copyable: false

{ "_id": 2 }
{ "_id": 1, "name": "Sandy Kane", "location": "Helena, MT" }
{ "_id": 8, "name": "Shayla Ray", "age": 20 }
{ "_id": 6, "name": "Zaynab Hassan", "age": 37 }

Unordered Execution
~~~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -280,8 +285,9 @@ operations to execute in any order:
.. code-block:: json
:copyable: false

{ "_id": 2 }
{ "_id": 3 }
{ "_id": 1, "name": "Sandy Kane", "location": "Helena, MT" }
{ "_id": 8, "name": "Shayla Ray", "age": 20 }
{ "_id": 6, "name": "Zaynab Omar", "age": 37 }

For more information about the methods and classes mentioned in this section,
see the following API Documentation:
Expand All @@ -302,4 +308,5 @@ There are 6 different ``WriteModel`` documents: ``InsertOneModel``,
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
- Unordered, which performs all the bulk operations in any order and reports errors
at the end, if any
120 changes: 64 additions & 56 deletions source/includes/fundamentals/code-snippets/BulkWrite.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,18 +52,22 @@ public static void main(String[] args) {
bulkWrite.insertExceptionExample();

System.out.println("Insert");
bulkWrite.setUpCollection();
bulkWrite.insertDocumentsExample();
bulkWrite.preview();

System.out.println("Replace");
bulkWrite.setUpCollection();
bulkWrite.replaceDocumentsExample();
bulkWrite.preview();

System.out.println("Update");
bulkWrite.setUpCollection();
bulkWrite.updateDocumentsExample();
bulkWrite.preview();

System.out.println("Delete");
bulkWrite.setUpCollection();
bulkWrite.deleteDocumentsExample();
bulkWrite.preview();
}
Expand All @@ -74,11 +78,11 @@ private void insertExceptionExample() {
try {
List<WriteModel<Document>> bulkOperations = new ArrayList<>();

InsertOneModel<Document> doc3 = new InsertOneModel<>(new Document("_id", 1));
InsertOneModel<Document> doc4 = new InsertOneModel<>(new Document("_id", 3));
InsertOneModel<Document> doc1 = new InsertOneModel<>(new Document("_id", 1));
InsertOneModel<Document> doc3 = new InsertOneModel<>(new Document("_id", 3));

bulkOperations.add(doc1);
bulkOperations.add(doc3);
bulkOperations.add(doc4);

collection.bulkWrite(bulkOperations);

Expand All @@ -91,16 +95,22 @@ private void insertExceptionExample() {
private void bulkWriteNotOrderedExample() {
List<WriteModel<Document>> bulkOperations = new ArrayList<>();

InsertOneModel<Document> doc1 = new InsertOneModel<>(new Document("_id", 3));
ReplaceOneModel<Document> doc2 = new ReplaceOneModel<>(Filters.eq("_id", 1),
new Document("_id", 1).append("x", 2));
UpdateOneModel<Document> doc3 = new UpdateOneModel<>(Filters.eq("_id", 3), Updates.set("x", 2));
DeleteManyModel<Document> doc4 = new DeleteManyModel<>(Filters.eq("x", 2));

InsertOneModel<Document> insertDoc = new InsertOneModel<>(new Document("_id", 6)
.append("name", "Zaynab Omar")
.append("age", 37));
ReplaceOneModel<Document> replaceDoc = new ReplaceOneModel<>(Filters.eq("_id", 1),
new Document("name", "Sandy Kane")
.append("location", "Helena, MT"));
UpdateOneModel<Document> updateDoc = new UpdateOneModel<>(Filters.eq("name", "Zaynab Omar"),
Updates.set("name", "Zaynab Hassan"));
DeleteManyModel<Document> deleteDoc = new DeleteManyModel<>(Filters.gt("age", 50));

bulkOperations.add(doc1);
bulkOperations.add(doc2);
bulkOperations.add(doc3);
bulkOperations.add(doc4);
bulkOperations.add(insertDoc);
bulkOperations.add(replaceDoc);
bulkOperations.add(updateDoc);
bulkOperations.add(deleteDoc);


// begin bulkWriteNotOrderedExample
BulkWriteOptions options = new BulkWriteOptions().ordered(false);
Expand All @@ -114,90 +124,79 @@ private void bulkWriteExample() {

List<WriteModel<Document>> bulkOperations = new ArrayList<>();

InsertOneModel<Document> doc1 = new InsertOneModel<>(new Document("_id", 3));
ReplaceOneModel<Document> doc2 = new ReplaceOneModel<>(Filters.eq("_id", 1),
new Document("_id", 1).append("x", 2));
UpdateOneModel<Document> doc3 = new UpdateOneModel<>(Filters.eq("_id", 3), Updates.set("x", 2));
DeleteManyModel<Document> doc4 = new DeleteManyModel<>(Filters.eq("x", 2));

InsertOneModel<Document> insertDoc = new InsertOneModel<>(new Document("_id", 6)
.append("name", "Zaynab Omar")
.append("age", 37));
ReplaceOneModel<Document> replaceDoc = new ReplaceOneModel<>(Filters.eq("_id", 1),
new Document("name", "Sandy Kane")
.append("location", "Helena, MT"));
UpdateOneModel<Document> updateDoc = new UpdateOneModel<>(Filters.eq("name", "Zaynab Omar"),
Updates.set("name", "Zaynab Hassan"));
DeleteManyModel<Document> deleteDoc = new DeleteManyModel<>(Filters.gt("age", 50));

bulkOperations.add(doc1);
bulkOperations.add(doc2);
bulkOperations.add(doc3);
bulkOperations.add(doc4);
bulkOperations.add(insertDoc);
bulkOperations.add(replaceDoc);
bulkOperations.add(updateDoc);
bulkOperations.add(deleteDoc);
Comment on lines +138 to +141
Copy link
Contributor

Choose a reason for hiding this comment

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

good change here!


collection.bulkWrite(bulkOperations);
//end bulkWriteExample
}

private void insertDocumentsExample(){
collection.drop();
List<WriteModel<Document>> bulkOperations = new ArrayList<>();

// begin insertDocumentsExample
InsertOneModel<Document> doc1 = new InsertOneModel<>(new Document("_id", 3));
InsertOneModel<Document> doc2 = new InsertOneModel<>(new Document("_id", 4));
InsertOneModel<Document> juneDoc = new InsertOneModel<>(new Document("name", "June Carrie")
.append("age", 17));
InsertOneModel<Document> kevinDoc = new InsertOneModel<>(new Document("name", "Kevin Moss")
.append("age", 22));
//end insertDocumentsExample

bulkOperations.add(doc1);
bulkOperations.add(doc2);
bulkOperations.add(juneDoc);
bulkOperations.add(kevinDoc);

collection.bulkWrite(bulkOperations);
}

private void replaceDocumentsExample(){
collection.drop();
List<WriteModel<Document>> bulkOperations = new ArrayList<>();

InsertOneModel<Document> doc1 = new InsertOneModel<>(new Document("_id", 1));
InsertOneModel<Document> doc2 = new InsertOneModel<>(new Document("_id", 2));

// begin replaceDocumentsExample
ReplaceOneModel<Document> doc3 = new ReplaceOneModel<>(
ReplaceOneModel<Document> celineDoc = new ReplaceOneModel<>(
Filters.eq("_id", 1),
new Document("_id", 1).append("x", 4));
new Document("name", "Celine Stork")
.append("location", "San Diego, CA"));
//end replaceDocumentsExample

bulkOperations.add(doc1);
bulkOperations.add(doc2);
bulkOperations.add(doc3);
bulkOperations.add(celineDoc);

collection.bulkWrite(bulkOperations);
}

private void updateDocumentsExample(){
collection.drop();
List<WriteModel<Document>> bulkOperations = new ArrayList<>();

InsertOneModel<Document> doc1 = new InsertOneModel<>(new Document("_id", 1));
InsertOneModel<Document> doc2 = new InsertOneModel<>(new Document("_id", 2));

// begin updateDocumentsExample
UpdateOneModel<Document> doc3 = new UpdateOneModel<>(
UpdateOneModel<Document> updateDoc = new UpdateOneModel<>(
Filters.eq("_id", 2),
Updates.set("x", 8));
Updates.set("age", 31));
//end updateDocumentsExample

bulkOperations.add(doc1);
bulkOperations.add(doc2);
bulkOperations.add(doc3);
bulkOperations.add(updateDoc);

collection.bulkWrite(bulkOperations);
}

private void deleteDocumentsExample(){
collection.drop();
List<WriteModel<Document>> bulkOperations = new ArrayList<>();

InsertOneModel<Document> doc1 = new InsertOneModel<>(new Document("_id", 1));
InsertOneModel<Document> doc2 = new InsertOneModel<>(new Document("_id", 2));

// begin deleteDocumentsExample
DeleteOneModel<Document> doc3 = new DeleteOneModel<>(Filters.eq("_id", 1));
DeleteOneModel<Document> deleteDoc = new DeleteOneModel<>(Filters.eq("_id", 1));
//end deleteDocumentsExample

bulkOperations.add(doc1);
bulkOperations.add(doc2);
bulkOperations.add(doc3);
bulkOperations.add(deleteDoc);

collection.bulkWrite(bulkOperations);
}
Expand All @@ -213,11 +212,20 @@ private void setUpCollection(){
List<WriteModel<Document>> bulkOperations = new ArrayList<>();
//end bulkOpsList

InsertOneModel<Document> doc1 = new InsertOneModel<>(new Document("_id", 1));
InsertOneModel<Document> doc2 = new InsertOneModel<>(new Document("_id", 2));
InsertOneModel<Document> karen = new InsertOneModel<>(new Document("_id", 1)
.append("name", "Karen Sandoval")
.append("age", 31));
InsertOneModel<Document> william = new InsertOneModel<>(new Document("_id", 2)
.append("name", "William Chin")
.append("age", 54));
InsertOneModel<Document> shayla = new InsertOneModel<>(new Document("_id", 8)
.append("name", "Shayla Ray")
.append("age", 20));

bulkOperations.add(doc1);
bulkOperations.add(doc2);
bulkOperations.add(karen);
bulkOperations.add(william);
bulkOperations.add(shayla);


collection.bulkWrite(bulkOperations);
}
Expand Down