DOCSP-49977 Replace One

Author: lindseymoore

source/crud/update/replace.txt

@@ -1,3 +1,5 @@
+.. _golang-replacement-document:
+
 =================
 Replace Documents
 =================
@@ -15,4 +17,110 @@ Replace Documents
 .. meta:: 
    :keywords: code example, go, write, add data, change
 
-.. TODO
+Overview
+--------
+
+In this guide, you can learn how to use {+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 `ReplaceOne() <{+api+}/mongo#Collection.ReplaceOne>`__ API Documentation.