DOCSP-30520: distinct usage example (#72)

Author: rustagir

snooty.toml

@@ -22,6 +22,8 @@ docs-branch = "master" # always set this to the docs branch (i.e. master, v2.6,
 version = "2.7.1" # always set this to the driver version (i.e. 2.6.0, 2.5.0, etc.)
 min-rust-version = "1.60" # always set this to the minimum supported Rust version
 api = "https://docs.rs/mongodb/{+version+}/mongodb"
+bson-version = "2.7.0"
+bson-api = "https://docs.rs/bson/{+bson-version+}/bson"
 stable-api = "Stable API"
 tracing-version = "0.1.37"
 tracing-sub-version = "0.3.17"

source/includes/usage-examples/code-snippets/distinct-async.rs

@@ -0,0 +1,30 @@
+use std::env;
+
+use mongodb::{ bson::doc, Client, Collection };
+use serde::{ Deserialize, Serialize };
+
+#[derive(Serialize, Deserialize, Debug)]
+struct Restaurant {
+    borough: String,
+    cuisine: String,
+}
+
+#[tokio::main]
+async fn main() -> mongodb::error::Result<()> {
+    let uri = "<connection string>";
+
+    let client = Client::with_uri_str(uri).await?;
+    let my_coll: Collection<Restaurant> = client
+        .database("sample_restaurants")
+        .collection("restaurants");
+
+    let filter = doc! { "cuisine": "Turkish" };
+    let boroughs = my_coll.distinct("borough", filter, None).await?;
+
+    println!("List of field values for 'borough':");
+    for b in boroughs.iter() {
+        println!("{:?}", b);
+    }
+
+    Ok(())
+}

source/includes/usage-examples/code-snippets/distinct-sync.rs

@@ -0,0 +1,29 @@
+use std::env;
+
+use mongodb::{ bson::doc, sync::{ Client, Collection } };
+use serde::{ Deserialize, Serialize };
+
+#[derive(Serialize, Deserialize, Debug)]
+struct Restaurant {
+    borough: String,
+    cuisine: String,
+}
+
+fn main() -> mongodb::error::Result<()> {
+    let uri = "<connection string>";
+
+    let client = Client::with_uri_str(uri)?;
+    let my_coll: Collection<Restaurant> = client
+        .database("sample_restaurants")
+        .collection("restaurants");
+
+    let filter = doc! { "cuisine": "Turkish" };
+    let boroughs = my_coll.distinct("borough", filter, None)?;
+
+    println!("List of field values for 'borough':");
+    for b in boroughs.iter() {
+        println!("{:?}", b);
+    }
+
+    Ok(())
+}

source/usage-examples.txt

@@ -19,6 +19,7 @@ Usage Examples
    /usage-examples/replace
    /usage-examples/deleteMany
    /usage-examples/count
+   /usage-examples/distinct
 
 Overview
 --------
@@ -99,11 +100,12 @@ Available Usage Examples
 - :ref:`Replace a Document <rust-replace-usage>`
 - :ref:`Delete Multiple Documents <rust-delete-many-usage>`
 - :ref:`Count Documents <rust-count-usage>`
-  
+- :ref:`List Distinct Field Values <rust-distinct-usage>`
+
 .. TODO: add Usage Example pages as they are created
     - :ref:`Insert a Document <rust-insert-one-usage>`
     - :ref:`Insert Multiple Documents <rust-insert-many-usage>`
     - :ref:`Update a Document <rust-update-one-usage>`
     - :ref:`Update Multiple Documents <rust-update-many-usage>`
     - :ref:`Delete a Document <rust-delete-one-usage>`
-    - :ref:`Find Distinct Values <rust-distinct-usage>`
+    - :ref:`Delete Multiple Documents <rust-delete-many-usage>`

source/usage-examples/count.txt

@@ -35,7 +35,7 @@ The following code first uses the ``estimated_document_count()`` method
 to count the total number of documents in the collection. Then, the
 example uses the ``count_documents()`` method to count the number of
 documents that match a query filter. The filter matches documents in which
-the value of the ``name`` field includes the string ``"Sunset"``.
+the value of the ``name`` field includes the string ``"Sunset"``:
 
 Select the **Asynchronous** or **Synchronous** tab to see the
 corresponding code for each runtime:

source/usage-examples/distinct.txt

@@ -0,0 +1,72 @@
+.. _rust-distinct-usage:
+
+==========================
+List Distinct Field Values
+==========================
+
+You can list the distinct field values of documents by calling the
+`distinct() <{+api+}/struct.Collection.html#method.distinct>`__ method
+on a ``Collection`` instance.
+
+Pass a field name as a parameter to the ``distinct()`` method to return
+the distinct values for that field. You can also pass a query filter as
+a parameter to find distinct field values from only a subset of matched
+documents. To learn more about creating query filters, see the
+:ref:`rust-query-guide` guide.
+
+The ``distinct()`` method returns the list of distinct values as a ``Vec<Bson>``
+type, a vector of `Bson <{+bson-api+}/enum.Bson.html>`__ values.
+
+Example
+-------
+
+This example finds distinct field values across the
+``restaurants`` collection of the ``sample_restaurants`` database. The
+example uses a ``Restaurant`` struct that has ``cuisine`` and
+``borough`` fields to model documents in the collection.
+
+The following code finds distinct values of the ``borough`` field in
+the subset of documents in which the value of the ``cuisine`` field
+is ``"Turkish"``:
+
+.. tabs::
+
+   .. tab:: Asynchronous
+      :tabid: find-async
+
+      .. io-code-block::
+         :copyable: true
+
+        .. input:: /includes/usage-examples/code-snippets/distinct-async.rs
+            :language: rust
+            :dedent:
+
+        .. output::
+            :language: console
+            :visible: false
+
+            List of field values for 'borough':
+            String("Brooklyn")
+            String("Manhattan")
+            String("Queens")
+            String("Staten Island")
+
+   .. tab:: Synchronous
+      :tabid: find-sync
+
+      .. io-code-block::
+         :copyable: true
+
+        .. input:: /includes/usage-examples/code-snippets/distinct-sync.rs
+            :language: rust
+            :dedent:
+
+        .. output::
+            :language: console
+            :visible: false
+
+            List of field values for 'borough':
+            String("Brooklyn")
+            String("Manhattan")
+            String("Queens")
+            String("Staten Island")