DOCSP-30518: Delete Many Usage Example (#67)

Author: norareidy

source/fundamentals/database-collection.txt

@@ -251,6 +251,8 @@ a database referenced by the ``db`` variable by using the
 
       ["my_coll", "coll_xyz", ...]
 
+.. _rust-drop-collection:
+
 Drop a Collection
 -----------------
 

source/includes/usage-examples/code-snippets/delete-many-async.rs

@@ -0,0 +1,40 @@
+use mongodb::{ 
+    bson::doc,
+    Client,
+    Collection 
+};
+use serde::{ Deserialize, Serialize };
+
+#[derive(Serialize, Deserialize, Debug)]
+struct Restaurant {
+    address: Address,
+    borough: String,
+}
+
+#[derive(Serialize, Deserialize, Debug)]
+struct Address {
+    street: 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! { "$and": [
+           doc! { "borough": "Manhattan" },
+           doc! { "address.street": "Broadway" }
+       ]
+    };
+
+    let result = my_coll.delete_many(filter, None).await?;
+
+    println!("Deleted documents: {}", result.deleted_count);
+
+    Ok(())
+}

source/includes/usage-examples/code-snippets/delete-many-sync.rs

@@ -0,0 +1,38 @@
+use mongodb::{
+    bson::doc,
+    sync::{Client, Collection}
+};
+use serde::{ Deserialize, Serialize };
+
+#[derive(Serialize, Deserialize, Debug)]
+struct Restaurant {
+    address: Address,
+    borough: String,
+}
+
+#[derive(Serialize, Deserialize, Debug)]
+struct Address {
+    street: 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! { "$and": [
+           doc! { "borough": "Manhattan" },
+           doc! { "address.street": "Broadway" }
+       ]
+    };
+
+    let result = my_coll.delete_many(filter, None)?;
+
+    println!("Deleted documents: {}", result.deleted_count);
+
+    Ok(())
+}

source/usage-examples.txt

@@ -13,6 +13,7 @@ Usage Examples
 .. toctree::
 
    /usage-examples/find
+   /usage-examples/deleteMany
    /usage-examples/count
 
 Overview
@@ -88,6 +89,7 @@ Available Usage Examples
 ------------------------
 
 - :ref:`Find Multiple Documents <rust-find-usage>`
+- :ref:`Delete Multiple Documents <rust-delete-many-usage>`
 - :ref:`Count Documents <rust-count-usage>`
 
 .. TODO: add Usage Example pages as they are created
@@ -98,7 +100,6 @@ Available Usage Examples
     - :ref:`Update Multiple Documents <rust-update-many-usage>`
     - :ref:`Replace a Document <rust-replace-usage>`
     - :ref:`Delete a Document <rust-delete-one-usage>`
-    - :ref:`Delete Multiple Documents <rust-delete-many-usage>`
     - :ref:`Find Distinct Values <rust-distinct-usage>`
 
 

source/usage-examples/deleteMany.txt

@@ -0,0 +1,76 @@
+.. _rust-delete-many-usage:
+
+=========================
+Delete Multiple Documents
+=========================
+
+You can delete multiple documents from a collection in a single operation
+by calling the `delete_many() <{+api+}/struct.Collection.html#method.delete_many>`__
+method on a ``Collection`` instance.
+
+Pass a query filter to the ``delete_many()`` method to delete documents in the
+collection that match the filter. If you do not include a filter, MongoDB deletes
+all the documents in the collection. 
+
+The ``delete_many()`` method returns a `DeleteResult <{+api+}/results/struct.DeleteResult.html>`__
+type. This type contains information about the delete operation, such as the total
+number of documents deleted.
+
+To learn more about delete operations, see the :ref:`rust-delete-guide` guide.
+
+.. tip::
+
+    To delete all documents in a collection, consider calling the ``drop()``
+    method on a ``Collection`` instance. To learn more about the ``drop()`` 
+    method, see the :ref:`rust-drop-collection` section of the Databases and
+    Collections guide.
+
+Example
+-------
+
+This example deletes all the documents from the ``restaurants`` collection that
+match a query filter. The example uses a ``Restaurant`` struct that has ``address``
+and ``borough`` fields to model the documents in the collection. 
+
+This example passes a query filter as a parameter to the ``delete_many()`` method.
+The filter matches documents where the value of the ``borough`` field is ``"Manhattan"``
+and the value of the ``address.street`` field is ``"Broadway"``.
+
+Select the **Asynchronous** or **Synchronous** tab to see corresponding code for each runtime:
+
+.. tabs::
+
+   .. tab:: Asynchronous
+      :tabid: delete-many-async
+
+      .. io-code-block::
+         :copyable: true
+
+        .. input:: /includes/usage-examples/code-snippets/delete-many-async.rs
+            :language: rust
+            :dedent:
+
+        .. output::
+            :language: console
+            :visible: false
+
+            // Your values might differ
+            Deleted documents: 615
+
+   .. tab:: Synchronous
+      :tabid: find-sync
+
+      .. io-code-block::
+         :copyable: true
+
+        .. input:: /includes/usage-examples/code-snippets/delete-many-sync.rs
+            :language: rust
+            :dedent:
+
+        .. output::
+            :language: console
+            :visible: false
+
+            // Your values might differ
+            Deleted documents: 615
+