Merge pull request #438 from norareidy/DOCSP-31089-fix-bulk-examples

DOCSP-31089: Improve bulk operation examples

Author: norareidy

source/fundamentals/crud/write-operations/bulk.txt

@@ -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
@@ -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:
@@ -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
@@ -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
@@ -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,
@@ -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
@@ -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
@@ -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
@@ -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
 ~~~~~~~~~~~~~~~~~
@@ -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
@@ -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
 ~~~~~~~~~~~~~~~~~~~
@@ -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:
@@ -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

source/includes/fundamentals/code-snippets/BulkWrite.java

@@ -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();
     }
@@ -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); 
 
@@ -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);
@@ -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);
 
         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);
     }
@@ -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);
     }