DOCSP-7602: adds bulkWrite usage example (#11)

* DOCSP-7602: adds bulkWrite usage example

* DOCSP-7602: standardize code & prose with other examples

* DOCSP-7602: it helps to save before committing

* cleaning up errors

* DOCSP-7602: wordsmithing

Author: schmalliso

.gitignore

@@ -5,3 +5,4 @@ build/
 .#*
 *.bak
 giza.log
+.vscode*

conf.py

@@ -61,7 +61,7 @@
 pygments_style = 'sphinx'
 
 extlinks = {
-    'manual': ('http://docs.mongodb.com/manual%s', ''),
+    'manual': ('https://docs.mongodb.com/manual%s', ''),
 }
 
 ## add `extlinks` for each published version.

source/code-snippets/usage-examples/bulkWrite-example.js

@@ -0,0 +1,59 @@
+const { MongoClient } = require("mongodb");
+const fs = require("fs");
+
+// Replace the following with your MongoDB deployment's connection
+// string.
+const uri =
+  "mongodb+srv://<user>:<password>@<cluster-url>?retryWrites=true&w=majority";
+
+const client = new MongoClient(uri, {
+  useNewUrlParser: true,
+  useUnifiedTopology: true
+});
+
+async function run() {
+  try {
+    await client.connect();
+
+    const mflix = client.db("sample_mflix");
+
+    // Replace with the path to your copy of the users.json file
+    var users = JSON.parse(fs.readFileSync("<path/to/users.json/file"));
+
+    var usersToInsert = [];
+
+    // Loop through each user in the users array and format the data from
+    // the JSON file to be a series of insertOne operations. Append
+    // each appropriately formatted object to the usersToInsert array.
+    users.forEach(user => {
+      usersToInsert.push({ insertOne: { document: user } });
+    });
+
+    // Perform the bulk write operation and print out the number
+    // of documents inserted and/or any error messages.
+    // This is a routine data import
+    // that does not rely on the ordering of the operations to ensure
+    // data consistency, so you can set the ordered option to false
+    // to improve write performance.
+    mflix
+      .collection("users")
+      .bulkWrite(usersToInsert, { ordered: false }, function(error, result) {
+        // The bulk write operation may successfully insert documents
+        // and also return an error, so both cases must be handled.
+        if (result.nInserted > 0) {
+          console.log("Number of documents inserted: " + result.nInserted);
+        } else {
+          console.log(
+            "No documents were inserted during the bulk write operation"
+          );
+        }
+
+        if (error) {
+          console.log("Error: " + error);
+        }
+      });
+  } finally {
+    await client.close();
+  }
+}
+run().catch(console.dir);

source/usage-examples.txt

@@ -4,18 +4,23 @@ Usage Examples
 
 .. default-domain:: mongodb
 
-:doc:`findOne </usage-examples/findOne>`
-:doc:`find </usage-examples/find>`
-:doc:`updateOne</usage-examples/updateOne>`
+:doc:`bulkWrite </usage-examples/bulkWrite>`
 :doc:`deleteMany </usage-examples/deleteMany>`
+:doc:`deleteOne </usage-examples/deleteOne>`
+:doc:`find </usage-examples/find>`
+:doc:`findOne </usage-examples/findOne>`
 :doc:`insertMany </usage-examples/insertMany>`
+:doc:`updateOne</usage-examples/updateOne>`
+
 
 .. toctree::
    :caption: Examples
 
-   /usage-examples/findOne
-   /usage-examples/find
-   /usage-examples/updateOne
+   /usage-examples/bulkWrite
    /usage-examples/deleteMany
    /usage-examples/deleteOne
+   /usage-examples/find
+   /usage-examples/findOne
+   /usage-examples/findOneAndUpdate
    /usage-examples/insertMany
+   /usage-examples/updateOne

source/usage-examples/.gitkeep

@@ -0,0 +1,93 @@
+=======================
+Perform Bulk Operations
+=======================
+
+.. default-domain:: mongodb
+
+Overview
+--------
+
+:node-api:`collection.bulkWrite <Collection.html#bulkWrite>` lets you
+perform bulk write operations against a *single* collection. With
+``collection.bulkWrite()``, you specify a list of operations to perform and
+MongoDB then executes those operations in bulk. Bulk write supports
+``insertOne``, ``updateOne``, ``updateMany``, ``deleteOne``,
+``deleteMany``, and ``replaceOne`` operations. Refer to the method
+documentation for full details.
+
+``bulkWrite()`` accepts the following parameters:
+
+- ``operations``: specifies the bulk operations to
+  perform. Each operation is passed to ``bulkWrite()`` as an object in
+  an array.
+
+- ``options``: *optional* settings that affect the execution
+  of the operation, such as :manual:`write concern
+  </reference/write-concern>` and order.
+
+  By default, MongoDB executes bulk operations one-by-one in the
+  specified order (i.e. serially). During an ordered bulk write, if
+  an error occurs during the processing of an operation, MongoDB returns without
+  processing the remaining operations in the list. In contrast,
+  when ``ordered`` is ``false``, MongoDB continues to process remaining
+  write operations in the list. Unordered operations are faster as
+  MongoDB can execute the operations in parallel, but the results of the
+  operation may vary. For example, a ``deleteOne`` operation run before
+  an ``updateMany`` operation might have a different result from running
+  it after the ``updateMany``. Refer to :manual:`Execution of Operations
+  </reference/method/db.collection.bulkWrite/#execution-of-operations>` for more
+  information.
+
+- ``callback``: command result callback. Like other collection methods,
+  ``bulkWrite()`` returns a Promise if you do not specify a callback. The
+  Promise resolves to a :node-api:`bulkWriteOpCallback </Collection.html#~bulkWriteOpCallback>` object containing the
+  result of the operation.
+
+``bulkWrite()`` returns a ``BulkWriteResult`` object
+that includes the number of updated or inserted documents, the ``_id`` of
+each document, and any ``writeError`` or ``writeConcernErrors``. Refer to
+the documentation for :node-api:`BulkWriteResult </BulkWriteResult>` for
+more information.
+
+If you create an index with a :manual:`unique constraint
+</core/index-unique>`, you might encounter a duplicate key write error
+during an operation. The following example shows a duplicate key error
+encountered when two of the users in the inserted sample dataset had the
+same email address. 
+
+.. code-block:: sh
+
+   Error during bulkWrite, BulkWriteError: E11000 duplicate key error collection: sample_mflix.users index: email_1 dup key: { : "[email protected]" }
+
+Similarly, if you attempt to perform a bulk write against a  collection
+that uses :manual:`schema validation </core/schema-validation>`, you may
+encounter warnings or errors related to the formatting of inserted or modified
+documents.
+
+Example
+-------
+
+The following code sample performs a bulk write operation against the
+``users`` collection in the ``sample_mflix`` database. Specifically, the
+program formats the data from a ``users.json`` source file to perform a
+series of ``insertOne`` operations with the ``bulkWrite()`` collection
+method. Download the dataset here: `users.json
+<https://raw.githubusercontent.com/mongodb-university/universal-driver-examples/master/users.json>`_.
+
+Documents in the ``users`` collection have ``email``, ``password``,
+and ``name`` fields, as well as the generated ``_id`` field.
+``users.json`` contains an array of objects that map directly to the
+existing fields in the collection, as in the following:
+
+.. code-block:: javascript
+
+   { 
+     "email" : "[email protected]",
+     "password" : "450f6704710dcf8033157978f7fbdfde",
+     "name" : "Marie Conrad"
+   }
+
+.. literalinclude:: /code-snippets/usage-examples/bulkWrite-example.js
+   :language: javascript
+
+