DOCSP-7608: nodejs usage example - collection distinct (#19)

* DOCSP-7608 usage example for collection distinct method

Author: Chris Cho

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

@@ -0,0 +1,30 @@
+// 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();
+
+    // define a database and collection on which to run the method
+    const database = client.db("sample_mflix");
+    const collection = database.collection("movies");
+
+    // specify the document field
+    const fieldName = "year";
+
+    // specify an optional query document
+    const query = { directors: "Barbra Streisand" };
+
+    const distinctValues = await collection.distinct(fieldName, query);
+    console.log(distinctValues);
+
+  } finally {
+    await client.close();
+  }
+}
+run().catch(console.dir);

source/usage-examples.txt

@@ -13,6 +13,7 @@ Usage Examples
 :doc:`findOne </usage-examples/findOne>`
 :doc:`insertMany </usage-examples/insertMany>`
 :doc:`updateOne</usage-examples/updateOne>`
+:doc:`distinct</usage-examples/distinct>`
 
 .. toctree::
    :caption: Examples
@@ -27,3 +28,4 @@ Usage Examples
    /usage-examples/findOneAndUpdate
    /usage-examples/insertMany
    /usage-examples/updateOne
+   /usage-examples/distinct

source/usage-examples/distinct.txt

@@ -0,0 +1,53 @@
+==========================================
+Distinct Values of a Field in a Collection
+==========================================
+
+.. default-domain:: mongodb
+
+You can retrieve a list of distinct values for a field across a collection
+by using the `distinct()
+<https://mongodb.github.io/node-mongodb-native/3.4/api/Collection.html#distinct>`_
+method. Call the ``distinct()`` method on a Collection object with
+a document field name parameter as a String to produce a list that contains
+one of each of the different values found in the specified document field.
+
+You can specify a document field within an *embedded document* using `dot
+notation
+<https://docs.mongodb.com/manual/core/document/#embedded-documents>`_. If
+you call ``distinct()`` on an document field that contains an array, each
+element of the array is treated as a separate value.
+
+You can provide an optional query document to narrow the set of documents that
+are searched and an optional Object to specify additional query parameters.
+For details on the optional parameters, see the
+`distinct() method in the API documentation
+<https://mongodb.github.io/node-mongodb-native/3.4/api/Collection.html#distinct>`_.
+
+The ``distinct()`` method returns a
+`Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_
+that resolves to an
+`Array <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array>`_
+that contains each of the different values. If none of the documents in the
+collection contain the field specified in the method call, it returns an
+empty Array.
+
+If you specify a value for the document field name that is not of type
+String such as a Document, Array, Number, or ``null``, the method does not
+execute and returns a TypeMismatch error with a message that resembles
+the following:
+
+::
+
+   "key" had the wrong type. Expected string, found <non-string type>
+
+
+Example
+-------
+
+The following snippet retrieves a list of distinct values for the ``year``
+document field from the ``movies`` collection. It uses a query document to
+match only movies that include "Barbara Streisand" as a ``director``.
+
+.. literalinclude:: /code-snippets/usage-examples/distinct.js
+  :language: javascript
+  :linenos: