DOCSP-34105: Update by ID example (#79)

Author: norareidy

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

@@ -64,6 +64,8 @@ The {+driver-short+} provides the following methods to change documents:
 You can retrieve and modify data in one action by using compound
 operations. To learn more, see the guide on :ref:`rust-compound-operations`.
 
+.. _rust-id:
+
 The _id Field
 ~~~~~~~~~~~~~
 
@@ -165,22 +167,22 @@ The following documents describe employees of a company:
    :copyable: false
 
    {
-     "_id": { ... },
+     "_id": ObjectId('4337'),
      "name": "Shelley Olson",
      "department": "Marketing",
      "role": "Director",
      "bonus": 3000
    },
    {
-     "_id": { ... },
+     "_id": ObjectId('4902'),
      "name": "Remi Ibrahim",
      "department": "Marketing",
      "role": "Consultant",
      "bonus": 1800
    }
 
-This example performs an update operation with the
-``update_many()`` method. The method has the following parameters:
+This example performs an update operation with the ``update_many()`` method.
+The ``update_many()`` method takes the following parameters:
 
 - A query filter to match documents where the value of the
   ``department`` field is ``"Marketing"``
@@ -204,28 +206,86 @@ This example performs an update operation with the
       :language: console
       :visible: false
 
-      Modified 2 document(s)
+      Modified documents: 2
 
-The following shows the updated documents resulting from the preceding update operation:
+The following documents reflect the changes resulting from the preceding update operation:
 
 .. code-block:: json
    :copyable: false
 
    {
-     "_id": { ... },
+     "_id": ObjectId('4337'),
      "name": "Shelley Olson",
      "department": "Business Operations",
      "role": "Analytics Specialist",
      "bonus": 3500
    },
    {
-     "_id": { ... },
+     "_id": ObjectId('4902'),
      "name": "Remi Ibrahim",
      "department": "Business Operations",
      "role": "Analytics Specialist",
      "bonus": 2300
    }
 
+Update by ObjectId Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following document describes an employee of a company:
+
+.. code-block:: json
+   :copyable: false
+   :emphasize-lines: 2
+
+   {
+     "_id": ObjectId('4274'),
+     "name": "Jill Millerton",
+     "department": "Marketing",
+     "role": "Consultant"
+   }
+
+This example queries for the preceding document by specifying a query filter to match the
+document's unique ``_id`` value. Then, the code performs an update operation with the
+``update_one()`` method. The ``update_one()`` method takes the following parameters:
+
+- Query filter that matches a document in which the value of the ``_id`` field is
+  ``ObjectId('4274')``
+
+- Update document that creates instructions to set the value of ``name`` to
+  ``"Jill Gillison"``
+
+.. io-code-block::
+
+   .. input:: /includes/fundamentals/code-snippets/crud/change.rs
+      :start-after: begin-update-by-id
+      :end-before: end-update-by-id
+      :language: rust
+      :dedent:
+
+   .. output:: 
+      :language: console
+      :visible: false
+
+      Modified documents: 1
+
+The following document reflects the changes resulting from the preceding update operation:
+
+.. code-block:: json
+   :copyable: false
+
+   {
+     "_id": ObjectId('4274'),
+     "name": "Jill Gillison",
+     "department": "Marketing",
+     "role": "Consultant"
+   }
+
+.. tip::
+
+   To learn more about the ``_id`` field, see the :ref:`_id Field <rust-id>`
+   section of this page or the :manual:`ObjectId() </reference/method/ObjectId/>`
+   method documentation in the Server manual.
+
 .. _rust-replace-document:
 
 Replace a Document
@@ -290,7 +350,7 @@ The following document describes an employee of a company:
    :copyable: false
 
    {
-     "_id": 4501,
+     "_id": ObjectId('4501'),
      "name": "Matt DeGuy",
      "role": "Consultant",
      "team_members": [ "Jill Gillison", "Susan Lee" ]
@@ -315,8 +375,8 @@ the preceding document with one that has the following fields:
       :language: console
       :visible: false
 
-      Matched 1 document(s)
-      Modified 1 document(s)
+      Matched documents: 1
+      Modified documents: 1
 
 The replaced document contains the contents of the replacement document
 and the immutable ``_id`` field:
@@ -325,7 +385,7 @@ and the immutable ``_id`` field:
    :copyable: false
 
    {
-     "_id": 4501,
+     "_id": ObjectId('4501'),
      "name": "Susan Lee",
      "role": "Lead Consultant",
      "team_members": [ "Jill Gillison" ]

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

@@ -1,5 +1,11 @@
 use bson::Document;
-use mongodb::{bson::doc, options::UpdateOptions, Client, Collection};
+use mongodb::{
+    bson::{doc, oid::ObjectId},
+    options::UpdateOptions,
+    Client,
+    Collection
+};
+use std::str::FromStr;
 use std::env;
 
 #[tokio::main]
@@ -11,17 +17,31 @@ async fn main() -> mongodb::error::Result<()> {
 
     // begin-update
     let update_doc = doc! {
-            "$set": doc!{ "department": "Business Operations",
+            "$set": doc! { "department": "Business Operations",
                           "role": "Analytics Specialist" },
-            "$inc": doc!{ "bonus": 500 }
+            "$inc": doc! { "bonus": 500 }
     };
 
     let res = my_coll
         .update_many(doc! { "department": "Marketing" }, update_doc, None)
         .await?;
-    println!("Modified {} document(s)", res.modified_count);
+    println!("Modified documents: {}", res.modified_count);
     // end-update
 
+    // begin-update-by-id
+    let id = ObjectId::from_str("4274").expect("Could not convert to ObjectId");
+    let filter_doc = doc! { "_id": id };
+
+    let update_doc = doc! {
+            "$set": doc! { "name": "Jill Gillison" }
+    };
+
+    let res = my_coll
+        .update_one(filter_doc, update_doc, None)
+        .await?;
+    println!("Modified documents: {}", res.modified_count);
+    // end-update-by-id
+
     // begin-replace
     let replace_doc = doc! {
         "name": "Susan Lee",
@@ -30,10 +50,10 @@ async fn main() -> mongodb::error::Result<()> {
     };
 
     let res = my_coll
-        .replace_one(doc! { "_id": 4501 }, replace_doc, None)
+        .replace_one(doc! { "name": "Matt DeGuy" }, replace_doc, None)
         .await?;
     println!(
-        "Matched {} document(s)\nModified {} document(s)",
+        "Matched documents: {}\nModified documents: {}",
         res.matched_count, res.modified_count
     );
     // end-replace