[Rust] use structs to model data instead of Document in CRUD fundamentals (#95)

Author: rachel-mack

source/fundamentals/crud/read-operations/cursor.txt

@@ -4,6 +4,13 @@
 Access Data by Using a Cursor
 =============================
 
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: loop, retrieve, process, batch
+
 .. contents:: On this page
    :local:
    :backlinks: none
@@ -53,16 +60,13 @@ This guide includes the following sections:
 Sample Data for Examples
 ------------------------
 
-The examples in this guide use the following sample documents. Each
-document describes a fruit:
+The examples in this guide use the following data stored in a struct:
 
-.. code-block:: json
-   :copyable: false
-   
-   { "name": "strawberry", "color": "red" },
-   { "name": "banana", "color": "yellow" },
-   { "name": "pomegranate", "color": "red" },
-   { "name": "pineapple", "color": "yellow" }
+.. literalinclude:: /includes/fundamentals/code-snippets/crud/cursor.rs
+   :language: rust
+   :dedent:
+   :start-after: start-sample-data
+   :end-before: end-sample-data
 
 .. _rust-cursor-individual:
 
@@ -130,8 +134,8 @@ collection:
       :language: console
       :visible: false
 
-      Document({"_id": ObjectId("..."), "name": String("strawberry"), "color": String("red")})
-      Document({"_id": ObjectId("..."), "name": String("pomegranate"), "color": String("red")})
+      Fruit { name: "strawberry", color: "red" }
+      Fruit { name: "pomegranate", color: "red" }
 
 .. _rust-cursor-indiv-stream:
 
@@ -178,12 +182,12 @@ collection:
       :visible: false
 
       Output from next() iteration:
-      { "_id": ObjectId("..."), "name": "strawberry", "color": "red" }
-      { "_id": ObjectId("..."), "name": "pomegranate", "color": "red" }
-      
+      Fruit { name: "strawberry", color: "red" }
+      Fruit { name: "pomegranate", color: "red" }
+
       Output from try_next() iteration:
-      { "_id": ObjectId("..."), "name": "banana", "color": "yellow" }
-      { "_id": ObjectId("..."), "name": "pineapple", "color": "yellow" }
+      Fruit { name: "banana", color: "yellow" }
+      Fruit { name: "pineapple", color: "yellow" }
 
 .. _rust-cursor-array:
 
@@ -220,10 +224,10 @@ You can use the following methods to retrieve documents as an array:
       :visible: false
 
       Output from collect():
-      [Ok(Document({"_id": ObjectId("..."), "name": String("strawberry"), "color": String("red")})), Ok(Document({"_id": ObjectId("..."), "name": String("pomegranate"), "color": String("red")}))]
-      
+      [Ok(Fruit { name: "strawberry", color: "red" }), Ok(Fruit { name: "pomegranate", color: "red" })]
+
       Output from try_collect():
-      [Document({"_id": ObjectId("..."), "name": String("banana"), "color": String("yellow")}), Document({"_id": ObjectId("..."), "name": String("pineapple"), "color": String("yellow")})]
+      [Fruit { name: "banana", color: "yellow" }, Fruit { name: "pineapple", color: "yellow" }]
 
 .. warning:: Avoid Exceeding Application Memory Limits
 

source/fundamentals/crud/read-operations/query.txt

@@ -94,16 +94,22 @@ Sample Data
 The examples in this guide use the following sample documents. Each
 document represents a fruit in a store's inventory and contains
 information about its quantity. Some documents contain additional fields
-that describe the fruit or its vendors:
+that describe the fruit or its vendors.
 
+.. literalinclude:: /includes/fundamentals/code-snippets/crud/query.rs
+   :language: rust
+   :dedent:
+   :start-after: begin-data-struct
+   :end-before: end-data-struct
 
-.. code-block:: json
-   :copyable: true
+The examples in the following sections query a collection of documents described by
+``Fruit`` structs:
 
-   { "_id": 1, "name": "orange", "quantity": 7 },
-   { "_id": 2, "name": "apple", "quantity": 4, "description": "Granny Smith" },
-   { "_id": 3, "name": "banana", "quantity": 36 },
-   { "_id": 4, "name": "pear", "quantity": 28, "vendors": ["A", "C" ] }
+.. literalinclude:: /includes/fundamentals/code-snippets/crud/query.rs
+   :language: rust
+   :dedent:
+   :start-after: begin-sample-docs
+   :end-before: end-sample-docs
 
 .. _rust-literal-values:
 
@@ -128,8 +134,7 @@ that has the value of ``"pear"``:
       :language: json
       :visible: false
 
-      Document({"_id": Int32(4), "name": String("pear"), "quantity":
-      Int32(28), "vendors": Array([String("A"), String("C")])})
+      Fruit { _id: "4", name: "pear", quantity: 28, description: None, vendors: Some(["A", "C"]) }
 
 .. note::
 
@@ -178,12 +183,9 @@ documents with a ``quantity`` value greater than ``5``:
       :language: json
       :visible: false
 
-      Document({"_id": Int32(1), "name": String("orange"), "quantity":
-      Int32(7)})
-      Document({"_id": Int32(3), "name": String("banana"), "quantity":
-      Int32(36)})
-      Document({"_id": Int32(4), "name": String("pear"), "quantity":
-      Int32(28), "vendors": Array([String("A"), String("C")])})
+      Fruit { _id: "1", name: "orange", quantity: 7, description: None, vendors: None }
+      Fruit { _id: "3", name: "banana", quantity: 36, description: None, vendors: None }
+      Fruit { _id: "4", name: "pear", quantity: 28, description: None, vendors: Some(["A", "C"]) }
 
 For more information on comparison operators, see :manual:`Comparison
 Query Operators </reference/operator/query-comparison/>` in the Server manual.
@@ -219,8 +221,7 @@ divisible by ``3``:
       :language: json
       :visible: false
 
-      Document({"_id": Int32(3), "name": String("banana"), "quantity":
-      Int32(36)})
+      Fruit { _id: "3", name: "banana", quantity: 36, description: None, vendors: None }
 
 .. note::
 
@@ -276,8 +277,17 @@ field:
       :language: json
       :visible: false
 
-      Document({"_id": Int32(2), "name": String("apple"), "quantity":
-      Int32(4), "description": String("Granny Smith")})
+      Fruit { _id: "2", name: "apple", quantity: 4, description: Some("Granny Smith"),
+      vendors: None }
+      
+.. note::
+   The :ref:`Fruit struct describing the documents<rust-query-sample-data>` in this guide
+   uses the ``#[serde(skip_serializing_if = "Option::is_none")]`` attribute on two of its
+   fields. This attribute specifies that the field be ignored if its value is ``None``. This
+   prevents a ``description`` value of ``None`` from being returned on an ``$exists`` query.
+   
+   See the `serialize_with <https://serde.rs/field-attrs.html#serialize_with>`__ Serde
+   attribute for more information.
 
 For a full list of element operators, see :manual:`Element
 Query Operators </reference/operator/query-element/>` in the Server manual.
@@ -312,8 +322,7 @@ for documents with a ``quantity`` value that is divisible by 3:
       :language: json
       :visible: false
 
-      Document({"_id": Int32(3), "name": String("banana"), "quantity":
-      Int32(36)})
+      Fruit { _id: "3", name: "banana", quantity: 36, description: None, vendors: None }
 
 For a full list of evaluation operators, see :manual:`Evaluation
 Query Operators </reference/operator/query-evaluation/>` in the Server manual.
@@ -347,8 +356,7 @@ bits set as ``7``, which is equivalent to  ``00000111`` in binary:
       :language: json
       :visible: false
 
-      Document({"_id": Int32(1), "name": String("orange"), "quantity":
-      Int32(7)})
+      Fruit { _id: "1", name: "orange", quantity: 7, description: None, vendors: None }
 
 For a full list of bitwise operators, see :manual:`Bitwise
 Query Operators </reference/operator/query-bitwise/>` in the Server manual.
@@ -381,8 +389,7 @@ contains ``"C"``:
       :language: json
       :visible: false
 
-      Document({"_id": Int32(4), "name": String("pear"), "quantity":
-      Int32(28), "vendors": Array([String("A"), String("C")])})
+      Fruit { _id: "4", name: "pear", quantity: 28, description: None, vendors: Some(["A", "C"]) }
 
 For a full list of bitwise operators, see :manual:`Array
 Query Operators </reference/operator/query-array/>` in the Server manual.

source/fundamentals/crud/read-operations/retrieve.txt

@@ -53,13 +53,11 @@ The examples in this guide use the following sample documents. Each
 document represents an item in a store's inventory and contains
 information about its categorization and unit price:
 
-.. code-block:: json
-   :copyable: false
-   
-   { "item": "candle", "category": "decor", "unit_price": 2.89 },
-   { "item": "blender", "category": "kitchen", "unit_price": 38.49 },
-   { "item": "placemat", "category": "kitchen", "unit_price": 3.19 },
-   { "item": "watering can", "category": "garden", "unit_price": 11.99 }
+.. literalinclude:: /includes/fundamentals/code-snippets/crud/retrieve.rs
+   :language: rust
+   :dedent:
+   :start-after: start-sample
+   :end-before: end-sample
 
 .. _rust-retrieve-find:
 
@@ -225,8 +223,8 @@ following parameters:
       :language: console
       :visible: false
 
-      { "_id": { ... }, "item": "watering can", "category": "garden", "unit_price": 11.99 }
-      { "_id": { ... }, "item": "candle", "category": "decor", "unit_price": 2.89 }
+      Inventory { item: "watering can", category: "garden", unit_price: 11.99 }
+      Inventory { item: "candle", category: "decor", unit_price: 2.89 }
 
 .. _rust-find-one-example:
 
@@ -254,20 +252,11 @@ following parameters:
       :visible: false
 
       Some(
-        Document({
-            "_id": ObjectId(
-                "...",
-            ),
-            "item": String(
-                "watering can",
-            ),
-            "category": String(
-                "garden",
-            ),
-            "unit_price": Double(
-                11.99,
-            ),
-        }),
+          Inventory {
+              item: "watering can",
+              category: "garden",
+              unit_price: 11.99,
+          },
       )
 
 .. _rust-retrieve-aggregation:
@@ -390,9 +379,9 @@ pipeline that contains the following stages:
       :language: console
       :visible: false
 
-      { "_id": { "category": "garden" }, "avg_price": 11.99 }
-      { "_id": { "category": "decor" }, "avg_price": 2.89 }
-      { "_id": { "category": "kitchen" }, "avg_price": 20.84 }
+      Document({"_id": Document({"category": String("decor")}), "avg_price": Double(2.890000104904175)})
+      Document({"_id": Document({"category": String("kitchen")}), "avg_price": Double(20.840000867843628)})
+      Document({"_id": Document({"category": String("garden")}), "avg_price": Double(11.989999771118164)})
 
 .. _rust-crud-retrieve-addtl-info:
 

source/fundamentals/crud/write-operations/insert.txt

@@ -105,7 +105,7 @@ document into the ``books`` collection:
       :language: console
       :visible: false
 
-      Inserted document with _id: ObjectId("...")
+      Inserted document with _id: 8
 
 .. include:: /includes/fundamentals/automatic-creation.rst
 
@@ -202,9 +202,9 @@ multiple documents into the ``books`` collection:
       :visible: false
 
       Inserted documents with _ids:
-      ObjectId("...")
-      ObjectId("...")
-      ObjectId("...")
+      Int32(5)
+      Int32(6)
+      Int32(7)
 
 .. include:: /includes/fundamentals/automatic-creation.rst
 

source/includes/fundamentals/code-snippets/crud/cursor.rs

@@ -1,18 +1,51 @@
-use bson::Document;
 use futures::{ StreamExt, TryStreamExt };
-use mongodb::{ bson::doc, Client, error::Result, options::{ FindOptions, CursorType } };
+use mongodb::{ bson::doc, bson::Document, Client, Collection, error::Result, options::{ FindOptions, CursorType } };
+
+use serde::{ Deserialize, Serialize };
+
+#[derive(Serialize, Deserialize, Debug)]
+struct Fruit {
+    name: String,
+    color: String
+}
 
 #[tokio::main]
-async fn main() -> Result<()> {
+async fn main() -> mongodb::error::Result<()> {
+    // Replace the placeholder with your Atlas connection string
     let uri = "<connection string>";
+
     let client = Client::with_uri_str(uri).await?;
 
-    let my_coll = client.database("db").collection::<Document>("fruits");
+    let my_coll: Collection<Fruit> = client.database("db").collection("fruits");
+
+    //start-sample-data
+    let docs = vec! [
+        Fruit { 
+            name: "strawberry".to_string(), 
+            color: "red".to_string() 
+        },
+        Fruit { 
+            name: "banana".to_string(), 
+            color: "yellow".to_string() 
+        },
+        Fruit { 
+            name: "pomegranate".to_string(), 
+            color: "red".to_string() 
+        },
+        Fruit { 
+            name: "pineapple".to_string(), 
+            color: "yellow".to_string() 
+        }
+    ];
+    //end-sample-data
+
+    // Inserts sample documents into the collection
+    let insert_many_result = my_coll.insert_many(docs, None).await?;
 
     // start-indiv-builtin
     let mut cursor = my_coll.find(doc! { "color": "red" }, None).await?;
     while cursor.advance().await? {
-        println!("{}", cursor.deserialize_current()?);
+        println!("{:?}", cursor.deserialize_current()?);
     }
     // end-indiv-builtin
 
@@ -22,14 +55,14 @@ async fn main() -> Result<()> {
     let mut cursor = my_coll.find(doc! { "color": "red" }, None).await?;
     println!("Output from next() iteration:");
     while let Some(doc) = cursor.next().await {
-        println!("{}", doc?);
+        println!("{:?}", doc?);
     }
 
     println!();
     let mut cursor = my_coll.find(doc! { "color": "yellow" }, None).await?;
     println!("Output from try_next() iteration:");
     while let Some(doc) = cursor.try_next().await? {
-        println!("{}", doc);
+        println!("{:?}", doc);
     }
     // end-indiv-stream
 
@@ -38,13 +71,13 @@ async fn main() -> Result<()> {
     // start-array
     let cursor = my_coll.find(doc! { "color": "red" }, None).await?;
     println!("Output from collect():");
-    let v: Vec<Result<Document>> = cursor.collect().await;
+    let v: Vec<Result<Fruit>> = cursor.collect().await;
     println!("{:?}", v);
 
     println!();
     let cursor = my_coll.find(doc! { "color": "yellow" }, None).await?;
     println!("Output from try_collect():");
-    let v: Vec<Document> = cursor.try_collect().await?;
+    let v: Vec<Fruit> = cursor.try_collect().await?;
     println!("{:?}", v);
     // end-array