DOCSP-7609: adds countDocuments and estimatedDocumentCount examples (#18)

* DOCSP-7609: adds countDocuments and estimatedDocumentCount exs

* DOCSP-7609: style fixes + use Promise not callback

Author: schmalliso

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

@@ -0,0 +1,40 @@
+// ignored first line
+const { MongoClient } = require("mongodb");
+
+// 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 database = client.db("sample_mflix");
+    const collection = database.collection("movies");
+
+    // Estimate the total number of documents in the collection
+    // and print out the count.
+    var estimate = await collection.estimatedDocumentCount();
+    console.log(
+      "Estimated number of documents in the movies collection: " + estimate,
+    );
+
+    // Query for movies from Canada.
+    const query = { countries: "Canada" };
+
+    // Find the number of documents that match the specified
+    // query, (i.e. with "Canada" as a value in the "countries" field)
+    // and print out the count.
+    var countCanada = await collection.countDocuments(query);
+    console.log("Number of movies from Canada: " + countCanada);
+  } finally {
+    await client.close();
+  }
+}
+run().catch(console.dir);

source/usage-examples.txt

@@ -5,6 +5,7 @@ Usage Examples
 .. default-domain:: mongodb
 
 :doc:`bulkWrite </usage-examples/bulkWrite>`
+:doc:`countDocuments and estimatedDocumentCount </usage-examples/count>`
 :doc:`deleteMany </usage-examples/deleteMany>`
 :doc:`insertOne </usage-examples/insertOne>`
 :doc:`deleteOne </usage-examples/deleteOne>`
@@ -17,6 +18,7 @@ Usage Examples
    :caption: Examples
 
    /usage-examples/bulkWrite
+   /usage-examples/count
    /usage-examples/deleteMany
    /usage-examples/deleteOne
    /usage-examples/insertOne

source/usage-examples/count.txt

@@ -0,0 +1,60 @@
+=============================================
+Count the Number of Documents in a Collection
+=============================================
+
+.. default-domain:: mongodb
+
+Overview
+--------
+
+The Node.js driver provides two methods for counting
+documents in a collection:
+
+- :node-api:`collection.countDocuments()
+  </Collection.html#countDocuments>` returns the number of documents in
+  the collection that match the specified query. If you specify a empty
+  query document, ``countDocuments()`` returns the total number of
+  documents in the collection.
+
+- :node-api:`collection.estimatedDocumentCount
+  </Collection.html#estimatedDocumentCount>` returns an
+  **estimation** of the number of documents in the collection based on
+  collection metadata.
+
+``estimatedDocumentCount()`` is faster than ``countDocuments()`` because
+the estimation is based on the collection's metadata rather than scanning
+the collection. In contrast,
+``countDocuments()`` takes longer to return, but provides an
+**accurate** count of the number of documents and supports specifying a
+filter. Choose the appropriate method for your workload.
+
+To specify which documents you wish to count, ``countDocuments()``
+accepts a :manual:`query </tutorial/query-documents>` parameter.
+``countDocuments()`` will only count the documents that match the
+specified query.
+
+``countDocuments()`` and ``estimatedDocumentCount()`` support optional
+settings that affect the method's execution. Refer to the reference
+documentation for each method for more information.
+
+Depending on whether you specify a Callback method, ``countDocuments()`` and ``estimatedDocumentCount()`` behave in two
+different ways:
+
+- If you do not specify a callback method, ``countDocuments()`` and
+  ``estimatedDocumentCount()`` return a Promise that resolves to a
+  number.
+
+- If you do specify a callback, ``countDocuments()`` and
+  ``estimatedDocumentCount`` return a :node-api:`countCallback
+  <Collection.html#~countCallback>` object.
+
+Example
+-------
+
+The following example estimates the number of documents in the ``movies``
+collection in the ``sample_mflix`` database, and then returns an accurate
+count of the number of documents in the ``movies`` collection with
+``Canada`` in the ``countries`` field.
+
+.. literalinclude:: /code-snippets/usage-examples/count.js
+  :language: javascript