(DOCSP-7601): insert many usage-example (#16)

* (DOCSP-7601): init insertMany

* Updated toc tree

* fixed wording on insertMany

* (DOCSP-7601): updated verbiage for clarity

Author: Mohammad Hunan Chughtai

source/code-snippets/usage-examples/insertMany.js

@@ -0,0 +1,32 @@
+// ignored first line
+const { MongoClient } = require("mongodb");
+
+const uri =
+  "mongodb+srv://<user>:<password>@<cluster-url>?retryWrites=true&w=majority";
+
+const client = new MongoClient(uri);
+
+async function run() {
+  try {
+    await client.connect();
+
+    const database = client.db("sample_mflix");
+    const collection = database.collection("movies");
+
+    // create a set of documents
+    const docOne = { name: "Red", town: "Kanto" };
+    const docTwo = { name: "Blue", town: "Kanto" };
+    const docThree = { name: "Leon", town: "Galar" };
+    // create a docs array and add the documents to the array
+    const docs = [docOne, docTwo, docThree];
+    // specify an additional options object
+    const options = {};
+    options.bypassDocumentValidation = true; // bypass document validation
+    options.ordered = true; // prevent additional documents from being prevented if one fails
+    const result = await collection.insertMany(docs, options);
+    console.log(`${result.insertedCount} documents were inserted`);
+  } finally {
+    await client.close();
+  }
+}
+run().catch(console.dir);

source/usage-examples.txt

@@ -8,6 +8,7 @@ Usage Examples
 :doc:`find </usage-examples/find>`
 :doc:`updateOne</usage-examples/updateOne>`
 :doc:`deleteMany </usage-examples/deleteMany>`
+:doc:`insertMany </usage-examples/insertMany>`
 
 .. toctree::
    :caption: Examples
@@ -16,4 +17,5 @@ Usage Examples
    /usage-examples/find
    /usage-examples/updateOne
    /usage-examples/deleteMany
-   /usage-examples/deleteOne
+   /usage-examples/deleteOne
+   /usage-examples/insertMany

source/usage-examples/insertMany.txt

@@ -0,0 +1,33 @@
+=====================
+Create Many Documents
+=====================
+
+.. default-domain:: mongodb
+
+You can create multiple documents using the `insertMany()
+<https://mongodb.github.io/node-mongodb-native/3.3/api/Collection.html#insertMany>`_
+method. The ``insertMany()`` takes an array of documents to insert into
+the specified collection.
+
+Create an `Object
+<https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object>`_
+to specify additional options.  Set the ``bypassDocumentValidation``
+field to bypass :manual:`schema validation <core/schema-validation/>`
+rules in MongoDB 3.2 or higher. Specify ``ordered:true`` to prevent
+inserting the remaining documents if the insertion failed for a previous
+document in the array.
+
+The ``insertMany()`` method returns a `Promise
+<https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_
+that resolves to an object. The ``insertedIds`` field of this object is
+an object that contains the ``_id`` of each inserted document. The
+``insertedCount`` field of this object is the number of documents
+inserted into the collection.
+
+Specifying incorrect parameters for your ``insertMany()`` operation can
+cause problems. Attempting to insert a field to a value that would violate
+unique index rules will throw a ``duplicate key error``.
+
+.. literalinclude:: /code-snippets/usage-examples/insertMany.js
+  :language: javascript
+  :linenos: