(DOCSP-39838) [CPP Driver] Write Data to MongoDB > Replace a Document (…

…mongodb#62)

* (DOCSP-49838) New pages for replace_one

* (DOCSP-39838) Build error.

* (DOCSP-39838) Edited write landing page to include replace page.

* (DOCSP-39838) Reordered options and results tables.

* (DOCSP-39838) Hint example.

* (DOCSP-39838) Build error fix.

* (DOCSP-39838) Adding separate section level for examples.

* (DOCSP-39838) Levels.

* (DOCSP-39838) Edits.

* (DOCSP-39838) Example edit.

* (DOCSP-39838) Edits.

* (DOCSP-39838) Updated the Write Data landing page to have replace code example.

* (DOCSP-39838) Updated the Write Data landing page code sample

* (DOCSP-39838) Updated the Write Data landing page code sample (added comment)

* (DOCSP-39838) Changes.

* (DOCSP-39838) Edit landing page code example.

* (DOCSP-39838) Include _id field mention in first paragraph.

* (DOCSP-39838) Edits.

* (DOCP-39838) Update links in table.

* (DOCSP-39838) edits.

* (DOCSP-39838) Added important admonition.

* (DOCSP-39838) Edits

* (DOCSP-39838) Edits

* (DOCSP-39838) Edit table header.

* (DOCSP-39838) Added comments to example.

* (DOCSP-39838) Indentation error.

* (DOCSP-39838) Table edits.

* (DOCSP-39838) Separated output from example.

* (DOCSP-39838) Example wording.

* (DOCSP-39838) Render error

* (DOCSP-39838) Example rendering fixes.

* (DOCSP-39838) Misc edits.

* (DOCSP-39838) Misc edits.

* (DOCSP-39838) Misc edits.

* (DOCSP-39838) Misc edits.

* (DOCSP-39838) Indent error

* (DOCSP-39838) Indent error

* (DOCSP-39838) Adding quotation marks to field values.

* (DOCSP-39838) @norareidy removed inline find_one() link.

* (DOCSP-39838) @norareidy Replace update with replace.

* (DOCSP-39838) @norareidy removed monospace from headers for style guide.

* (DOCSP-39838) @norareidy Swapping field and function.

* (DOCSP-39838) @norareidy Condensing example introduction.

* (DOCSP-39838) @norareidy Condensing example introduction.

* (DOCSP-39838) @norareidy Condensing and wording edits for example introductions.

* (DOCSP-39838) @norareidy Adding warning that sample ID may differ.

* (DOCSP-39838) @norareidy Bolded first instance of replace operation and replaced link for hint field.

* (DOCSP-39838) @norareidy Header underline fix.

* (DOCSP-39838) Adding context to links.

* (DOCSP-39838) @norareidy review edits.

* (DOCSP-39838) @norareidy Final review changes.

* (DOCSP-39838) @kevinAlbs comment fixes.

---------

Co-authored-by: Elyse Foreman <[email protected]>

source/includes/usage-examples/write-code-examples.cpp

@@ -57,6 +57,16 @@ int main() {
         // end-update-multiple
     }
 
+    {
+        // Replaces a document that matches the specified criteria
+        // start-replace-one
+        auto query_filter = make_document(kvp("<field to match>", "<value to match>"));
+        auto replace_doc = make_document(make_document(kvp("<field name>", "<value>")));
+
+        auto result = collection.replace_one(query_filter.view(), replace_doc.view());
+        // end-replace-one 
+    }
+
     {
         // Deletes a document that matches the specified criteria
         // start-delete-one

source/includes/write/replace.cpp

@@ -0,0 +1,103 @@
+#include <iostream>
+
+#include <bsoncxx/builder/basic/document.hpp>
+#include <bsoncxx/json.hpp>
+#include <mongocxx/client.hpp>
+#include <mongocxx/instance.hpp>
+#include <mongocxx/uri.hpp>
+
+using bsoncxx::builder::basic::kvp;
+using bsoncxx::builder::basic::make_document;
+
+int main() {
+    mongocxx::instance instance;
+    mongocxx::uri uri("<connection string>");
+    mongocxx::client client(uri);
+
+    // start-db-coll
+    auto db = client["sample_restaurants"];
+    auto collection = db["restaurants"];
+    // end-db-coll
+
+    {
+        // replaces a document that has a "name" value of "Nobu"
+        // with a document that has a "name" of "La Bernadin"
+        // start-replace-one
+        auto query_filter = make_document(kvp("name", "Nobu"));
+        auto replace_doc = make_document(kvp("name", "La Bernadin"));
+
+        auto result = collection.replace_one(query_filter.view(), replace_doc.view());
+        // end-replace-one
+    }
+
+    {
+        // Retrieves a document to verify the replacement operation
+        // start-replace-one-io
+        auto new_doc = collection.find_one(make_document(kvp("name", "La Bernadin")));
+        std::cout << "New document: " << bsoncxx::to_json(*new_doc) << std::endl;
+        // end-replace-one-io
+    }
+
+    {
+        // Replaces a document that has a "name" value of "Nobu" and instructs the operation to use the "name" field index
+        // start-replace-options-hint
+        auto index_specification = make_document(kvp("name", 1));
+        collection.create_index(index_specification.view());
+
+        mongocxx::options::replace opts{}; 
+        opts.hint(mongocxx::hint{"name_1"});
+
+        auto query_filter = make_document(kvp("name", "Nobu"));
+        auto replace_doc = make_document(kvp("name", "La Bernadin"));
+
+        auto result = collection.replace_one(query_filter.view(), replace_doc.view(), opts);
+        // end-replace-options-hint 
+    }
+
+    {
+        // Replaces a document that has a "name" value of "In-N-Out Burger" 
+        // and instructs the operation to insert a new operation if none match.
+        // start-replace-options-upsert
+        std::cout << "Total document count before replace_one(): " << collection.count_documents({}) << std::endl;
+
+        mongocxx::options::replace opts{}; 
+        opts.upsert(true);
+
+        auto query_filter = make_document(kvp("name", "In-N-Out Burger"));
+        auto replace_doc = make_document(kvp("name", "Shake Shack"));
+
+        auto result = collection.replace_one(query_filter.view(), replace_doc.view(), opts);
+
+        std::cout << "Total document count after replace_one(): " << collection.count_documents({}) << std::endl;
+        // end-replace-options-upsert
+    }
+
+    {
+        // Replaces the matching document and prints the number of matched documents
+        // start-replace-result-matched
+        auto query_filter = make_document(kvp("name", "Shake Shack"));
+        auto replace_doc = make_document(kvp("name", "In-N-Out Burger"));
+
+        auto result = collection.replace_one(query_filter.view(), replace_doc.view());
+        std::cout << "Matched documents: " << result->matched_count() << std::endl;        
+        // end-replace-result-matched
+    }
+
+    {
+
+        // Replaces a document that has a "name" value of "In-N-Out Burger" and instructs the operation
+        // to insert a new document if none match.
+        // start-replace-result-upsert
+        mongocxx::options::replace opts{}; 
+        opts.upsert(true);
+
+        auto query_filter = make_document(kvp("name", "In-N-Out Burger"));
+        auto replace_doc = make_document(kvp("name", "Shake Shack"));
+
+        auto result = collection.replace_one(query_filter.view(), replace_doc.view(), opts);
+        auto id = result->upserted_id()->get_value();
+
+        std::cout << "Upserted ID: " << id.get_oid().value.to_string() << std::endl;
+        // end-replace-result-upsert
+    }
+}

source/write.txt

@@ -24,6 +24,7 @@ Write Data to MongoDB
 
    /write/insert
    /write/update
+   /write/replace 
    /write/delete
    /write/bulk-write
 
@@ -115,9 +116,19 @@ or editing a field:
 To learn more about the ``update_many()`` method, see the
 :ref:`Update Documents <cpp-write-update>` guide.
 
-.. TODO:
- Replace One
- -----------
+Replace One
+-----------
+
+The following code shows how to replace a single document in a collection: 
+
+.. literalinclude:: /includes/usage-examples/write-code-examples.cpp
+   :start-after: start-replace-one
+   :end-before: end-replace-one
+   :language: cpp
+   :dedent:
+
+To learn more about the ``replace_one()`` method, see the 
+:ref:`Replace Documents <cpp-write-replace>` guide. 
 
 Delete One
 ----------