DOCSP-7607: Delete multiple documents usage example (#10)

Author: nathan-contino-mongo

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

@@ -0,0 +1,29 @@
+// 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");
+    // Query for all movies with the title "Santa Claus"
+    const query = { title: "Santa Claus" };
+
+    collection.deleteMany(query, options, function(err, r) {
+      if (err) {
+        console.log("Error: " + err.errmsg);
+      } else {
+        console.log("Deleted " + r.deletedCount + " documents");
+      }
+    });
+  } finally {
+    await client.close();
+  }
+}
+run().catch(console.dir);

source/usage-examples.txt

@@ -6,11 +6,14 @@ Usage Examples
 
 :doc:`findOne </usage-examples/findOne>`
 :doc:`find </usage-examples/find>`
+:doc:`deleteMany </usage-examples/deleteMany>`
 :doc:`findOneAndDelete </usage-examples/findOneAndDelete>`
 
+
 .. toctree::
    :caption: Examples
 
    /usage-examples/findOne
    /usage-examples/find
+   /usage-examples/deleteMany
    /usage-examples/findOneAndDelete

source/usage-examples/deleteMany.txt

@@ -0,0 +1,58 @@
+=====================
+Delete Many Documents
+=====================
+
+.. default-domain:: mongodb
+
+Overview
+--------
+
+You can delete several documents in a collection at once with
+``collection.deleteMany()``.
+The ``deleteMany()`` method uses a query document that you provide
+to match only the subset of the documents in the collection that match
+the query. If you don't provide a query document (or if you provide an
+empty document), MongoDB matches all documents in the collection. All
+matched documents are deleted. While you can use ``deleteMany()`` to
+delete all documents in a collection, consider using
+`drop() <http://mongodb.github.io/node-mongodb-native/3.4/api/Collection.html#drop>`_
+instead for better performance and clearer code.
+
+You can define additional query options using the ``options``
+object passed as the second parameter of the ``deleteMany()`` method.
+You can also pass a
+`callback method <https://mongodb.github.io/node-mongodb-native/3.3/api/Collection.html#~deleteWriteOpCallback>`_
+as an optional third parameter. For detailed reference documentation,
+see
+`collection.deleteMany() <https://mongodb.github.io/node-mongodb-native/3.3/api/Collection.html#deleteMany>`_.
+
+``deleteMany()`` behaves in two different ways depending on
+whether or not a callback method is provided:
+
+- if no callback method is provided, ``deleteMany()`` returns a
+  `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_
+  that resolves to an
+  `Object <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object>`_
+
+- if a callback method is provided, ``deleteMany()`` returns
+  nothing, and instead passes the result object or error object to the
+  provided callback method
+
+The
+`result object <http://mongodb.github.io/node-mongodb-native/3.2/api/Collection.html#~deleteWriteOpResult>`_
+contains multiple keys in the event of a successful
+execution. You can use the ``deletedCount`` key to determine the number
+of documents deleted by the operation.
+
+The error object contains ``errmsg``, a human-readable explanation of
+what caused the operation to fail.
+
+Example
+-------
+
+The following snippet deletes multiple documents from the ``movies``
+collection. It uses a **query document** that configures the query to
+match and delete only movies with the title "Santa Claus".
+
+.. literalinclude:: /code-snippets/usage-examples/deleteMany.js
+  :language: javascript