DOCSP-49977 Replace One

source/connect.txt

@@ -24,8 +24,8 @@ Connection Guide
    :titlesonly:
    :maxdepth: 1
 
-   Create a MongoClient <connect/mongoclient>
-   Choose a Connection Target <connect/connection-targets>
+   Create a MongoClient </connect/mongoclient>
+   Choose a Connection Target </connect/connection-targets>
    Connection Options </connect/specify-connection-options>
    Connection Troubleshooting </connect/connection-troubleshooting>
 

source/crud/update.txt

@@ -19,7 +19,12 @@ Modify Documents
    :depth: 2
    :class: singlecol
 
-.. TODO edit
+.. toctree::
+   :caption: Update Documents
+
+   Replace Documents </crud/update/replace>
+   Update Arrays </crud/update/embedded-arrays>
+   Upsert </crud/update/upsert>
 
 Overview
 --------
@@ -312,7 +317,7 @@ following usage examples:
 
 - :ref:`golang-update-one`
 - :ref:`golang-update-many`
-- :ref:`golang-replace`
+- :ref:`golang-replacement-document`
 
 To learn more about the operations mentioned, see the following
 guides:

source/crud/update/replace.txt

@@ -1,3 +1,6 @@
+.. _golang-replacement-document:
+.. _golang-replace:
+
 =================
 Replace Documents
 =================
@@ -15,4 +18,113 @@ Replace Documents
 .. meta:: 
    :keywords: code example, go, write, add data, change
 
-.. TODO
+Overview
+--------
+
+In this guide, you can learn how to use the {+driver-short+} to perform a replace
+operation on a document in a MongoDB collection. A replace operation performs
+differently than an update operation. An update operation
+modifies only the specified fields in a target document. A replace operation removes 
+all fields in the target document and replaces them with new ones.
+
+Parameters
+----------
+
+``ReplaceOne()`` expects a **replacement document**, which is the document
+that you want to take the place of an existing document. Replacement
+documents use the following format:
+
+.. code-block:: go
+
+   bson.D{{"<field>", "<value>"}, {"<field>", "<value>"}, ... }
+
+Return Values
+-------------
+
+``ReplaceOne()`` returns an ``UpdateResult`` type that
+contains information about the replace operation if the operation is
+successful. The ``UpdateResult`` type contains the following properties:
+
+.. list-table::
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Property
+     - Description
+
+   * - ``MatchedCount`` 
+     - The number of documents matched by the filter
+
+   * - ``ModifiedCount`` 
+     - The number of documents modified by the operation
+
+   * - ``UpsertedCount`` 
+     - The number of documents upserted by the operation
+
+   * - ``UpsertedID`` 
+     - The ``_id`` of the upserted document, or ``nil`` if there is none
+
+If multiple documents match the query filter passed to ``ReplaceOne()``,
+the method selects and replaces the first matched document. Your replace
+operation fails if no documents match the query filter.
+
+Example
+-------
+
+The following document describes a kitchen item:
+
+.. code-block:: json
+   :copyable: false
+
+   {
+      "_id" : 2056,
+      "item" : "Mug",
+      "brand" : "Simply Ceramics",
+      "price" : 2.99,
+      "material" : "Glass"
+   }
+
+The following example uses the ``ReplaceOne()`` method to substitute
+this document with one that contains an ``item`` field with a
+value of "Cup" and a ``quantity`` field with a value of 107:
+
+.. io-code-block::
+   :copyable: true
+
+   .. input::
+      :language: go
+
+      filter := bson.D{{"_id", 2056}}
+      replacement := bson.D{{"item", "Cup"}, {"quantity", 107}}
+
+      result, err := collection.ReplaceOne(context.TODO(), filter, replacement)
+      fmt.Printf("Documents matched: %v\n", result.MatchedCount)
+      fmt.Printf("Documents replaced: %v\n", result.ModifiedCount)
+
+   .. output::
+      :language: none
+      :visible: false
+
+      Documents matched: 1
+      Documents replaced: 1
+
+The replaced document contains the contents of the replacement document
+and the immutable ``_id`` field as follows:
+
+.. code-block:: json
+   :copyable: false
+
+   {
+      "_id" : 2056,
+      "item" : "Cup",
+      "quantity" : 107
+   }
+
+API Documentation
+-----------------
+
+To learn more about any of the methods or types discussed in this
+guide, see the following API Documentation: 
+
+- `ReplaceOne() <{+api+}/mongo#Collection.ReplaceOne>`__
+- `UpdateResult <{+api+}/mongo#UpdateResult>`__