DOCSP-26545 Fundamentals > ReplaceOne (#47)

* add replace method

* replaceOne changes

* fixes

* fixes

* fixes

* fixes

* fixes

* fixes

* dd feedback

* db feedback

Author: mongoKart

source/fundamentals/crud/write-operations.txt

@@ -12,5 +12,5 @@ Write Operations
    :caption: Write Operations
 
    /fundamentals/crud/write-operations/insert
-   /fundamentals/crud/write-operations/update
+   /fundamentals/crud/write-operations/change
    /fundamentals/crud/write-operations/delete

source/fundamentals/crud/write-operations/update.txt renamed to source/fundamentals/crud/write-operations/change.txt

@@ -1,7 +1,7 @@
-.. _csharp-update-guide:
+.. _csharp-change-guide:
 
 ================
-Update Documents
+Change Documents
 ================
 
 .. default-domain:: mongodb
@@ -15,8 +15,11 @@ Update Documents
 Overview
 --------
 
-In this guide, you'll learn how to edit existing documents or upsert new documents 
-in your MongoDB collections using update operations.
+In this guide, you can learn how to change documents in a MongoDB
+collection using two different kinds of operations: 
+
+- :ref:`Update <csharp-update-operation>`
+- :ref:`Replace <csharp-replace-operation>`
 
 Sample Data
 ~~~~~~~~~~~
@@ -25,7 +28,7 @@ The examples in this guide use the ``restaurants`` collection
 from the ``sample_restaurants`` database. The documents in this
 collection use the following ``Restaurant`` class as a model:
 
-.. literalinclude:: /includes/fundamentals/code-examples/crud/update/Restaurant.cs
+.. literalinclude:: /includes/fundamentals/code-examples/crud/change/Restaurant.cs
    :language: csharp
    :dedent:
    :start-after: start-model
@@ -35,6 +38,8 @@ This collection is from the :atlas:`sample datasets </sample-data>` provided
 by Atlas. See the :ref:`<csharp-quickstart>` to learn how to create a free MongoDB cluster
 and load this sample data.
 
+.. _csharp-update-operation:
+
 Update Operations
 -----------------
 
@@ -59,11 +64,12 @@ Each update method requires the following parameters:
 The {+driver-short+} provides a ``Builders`` class that simplifies the creation of both
 query filters and update documents. The following code sample uses ``Builders`` to create
 two documents for use as parameters in an update operation:
+
 - A query filter that searches for restaurants with a ``borough`` field value of "Manhattan" 
 - An update document that sets the value of the ``borough`` field of these restaurants 
-to "Manhattan (north)"
+  to "Manhattan (north)"
 
-.. literalinclude:: /includes/fundamentals/code-examples/crud/update/Update.cs
+.. literalinclude:: /includes/fundamentals/code-examples/crud/change/Update.cs
    :language: csharp
    :dedent:
    :start-after: start-builders
@@ -129,13 +135,13 @@ update all matched documents.
 .. tip::
 
    Find runnable examples that use these methods under :ref:`Additional
-   Information <csharp-update-info>`.
+   Information <csharp-change-info>`.
 
 Customize the Update Operation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Both methods optionally take an ``UpdateOptions`` type as an additional parameter,
-which represents options you can use to configure the delete operation.
+Both methods optionally accept an ``UpdateOptions`` object as an additional parameter,
+which represents options you can use to configure the update operation.
 If you don't specify any ``UpdateOptions`` properties, the driver does
 not customize the update operation.
 
@@ -183,7 +189,7 @@ following properties:
 
    * - ``Let``
      - | Gets or sets the let document. 
-         See :manual:`the MongoDB server manual </reference/command/update/#std-label-update-command-upsert>`
+         See :manual:`the MongoDB server manual </reference/command/update/#std-label-update-let-syntax>`
          for more information.
 
 Return Value
@@ -265,33 +271,226 @@ match any existing documents.
    ``UpdateMany()``, the driver would update only the first of the
    matched documents.
 
-.. _csharp-update-info:
+.. _csharp-replace-operation:
+
+Replace Operation
+-----------------
+
+You can perform a replace operation in MongoDB with the ``ReplaceOne()`` method. 
+This method removes all fields (except the ``_id`` field) from the first document that
+matches the search criteria, then inserts the fields and values you specify into the 
+document.
+
+Required Parameters
+~~~~~~~~~~~~~~~~~~~
+
+The ``ReplaceOne()`` method requires the following parameters:
+
+- A query filter document, which determines which record to replace. 
+- A **replacement** document, which specifies the fields and values to insert in the new 
+  document. If the documents in your collection are mapped to a {+language+} class,
+  the replacement document can be an instance of this class. 
+
+Like in an update operation, you can use the ``Builders`` class in the {+driver-short+} 
+to create a query filter. 
+The following code sample uses ``Builders`` to create a query filter that searches 
+for restaurants with a ``name`` field value of "Pizza Town". The code also creates a new 
+``Restaurant`` object that will replace the first matched document. 
+
+.. literalinclude:: /includes/fundamentals/code-examples/crud/change/Replace.cs
+   :language: csharp
+   :dedent:
+   :start-after: // start-parameters 
+   :end-before: // end-parameters 
+
+.. important::
+
+   The values of ``_id`` fields are immutable. If your replacement document specifies 
+   a value for the ``_id`` field, it must match the ``_id`` value of the existing document.
+
+The following code shows how to use the asynchronous ``ReplaceOneAsync()`` method 
+or the synchronous ``ReplaceOne()`` method to replace one document.
+
+.. tabs::
+
+   .. tab:: Asynchronous
+      :tabid: replace-one-async
+
+      .. code-block:: csharp
+         :copyable: true
+
+         var result = await _restaurantsCollection.ReplaceOneAsync(filter, newRestaurant);
+
+   .. tab:: Synchronous
+      :tabid: replace-one-sync
+
+      .. code-block:: csharp
+         :copyable: true
+
+         var result = _restaurantsCollection.ReplaceOne(filter, newRestaurant);
+
+.. tip::
+
+   Find runnable examples that use these methods under :ref:`Additional
+   Information <csharp-change-info>`.
+
+Customize the Replace Operation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``ReplaceOne()`` method optionally accepts a ``ReplaceOptions`` object as an 
+additional parameter, which represents options you can use to configure the replace 
+operation. If you don't specify any ``ReplaceOptions`` properties, the driver does
+not customize the replace operation.
+
+The ``ReplaceOptions`` type allows you to configure options with the
+following properties:
+
+.. list-table::
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Property
+     - Description
+
+   * - ``BypassDocumentValidation``
+     - | Specifies whether the replace operation bypasses document validation. This lets you 
+         replace documents that don't meet the schema validation requirements, if any 
+         exist. See :manual:`the MongoDB server manual</core/schema-validation/#schema-validation>`
+         for more information on schema validation.
+
+   * - ``Collation``
+     - | Specifies the kind of language collation to use when sorting
+         results. See :manual:`the MongoDB server manual</reference/collation/#std-label-collation>`
+         for more information on collation.
+
+   * - ``Comment``
+     - | Gets or sets the user-provided comment for the operation. 
+         See :manual:`the MongoDB server manual</reference/command/update/#command-fields>`
+         for more information.
+
+   * - ``Hint``
+     - | Gets or sets the index to use to scan for documents. 
+         See :manual:`the MongoDB server manual</reference/command/update/#std-label-update-command-hint>`
+         for more information.
+
+   * - ``IsUpsert``
+     - | Specifies whether the replace operation performs an upsert operation if no 
+         documents match the query filter. 
+         See :manual:`the MongoDB server manual </reference/command/update/#std-label-update-command-upsert>`
+         for more information.
+
+   * - ``Let``
+     - | Gets or sets the let document. 
+         See :manual:`the MongoDB server manual </reference/command/update/#std-label-update-let-syntax>`
+         for more information.
+
+Return Value
+~~~~~~~~~~~~
+
+The ``ReplaceOne()`` method returns a ``ReplaceOneResult`` 
+object. The ``ReplaceOneResult`` type contains the following properties:
+
+.. list-table::
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Property
+     - Description
+
+   * - ``IsAcknowledged``
+     - | Indicates whether the replace operation was acknowledged by MongoDB.
+
+   * - ``IsModifiedCountAvailable``
+     - | Indicates whether you can read the count of replaced records on the
+         ``ReplaceOneResult``.
+
+   * - ``MatchedCount``
+     - | The number of documents that matched the query filter, regardless of
+         whether one was replaced. 
+
+   * - ``ModifiedCount``
+     - | The number of documents replaced by the replace operation. 
+
+   * - ``UpsertedId``
+     - | The ID of the document that was upserted in the database, if the driver
+         performed an upsert.
+
+Example
+~~~~~~~
+
+The following code uses the ``ReplaceOne()`` method to find the first document where the 
+``name`` field has the value "Pizza Town", then replaces this document 
+with a new ``Restaurant`` document named "Food World". Because the ``IsUpsert`` option is 
+set to ``true``, the driver inserts a new document if the query filter doesn't 
+match any existing documents.
+
+.. io-code-block::
+   :copyable: true
+
+   .. input::
+      :language: csharp
+
+      var filter = Builders<Restaurant>.Filter.Eq(restaurant => restaurant.Name, "Pizza Town");
+
+      Restaurant newRestaurant = new()
+      {
+          Name = "Food World",
+          Cuisine = "American",
+          Address = new BsonDocument
+          {
+              {"street", "Food St"},
+              {"zipcode", "10003"},
+          },
+          Borough = "Manhattan",
+      };
+
+      ReplaceOptions opts = new ReplaceOptions()
+      {
+          Comment = new BsonString("Restaurant replaced for {+driver-short+} Fundamentals"),
+          IsUpsert = true
+      };
+
+      WriteLine("Replacing document...");
+      var result = _restaurantsCollection.ReplaceOne(filter, newRestaurant, opts);
+      
+      WriteLine($"Replaced documents: {result.ModifiedCount}");
+      WriteLine($"Result acknowledged? {result.IsAcknowledged}"); 
+
+   .. output::
+      :language: none
+      :visible: false
+      
+      Replacing document...
+      Replaced documents: 1
+      Result acknowledged? True
+
+.. _csharp-change-info:
 
 Additional Information
 ----------------------
 
-For runnable examples of the delete operations, see the following usage
+For runnable examples of the update and replace operations, see the following usage
 examples:
 
 - :ref:`csharp-update-one`
 - :ref:`csharp-update-many`
+- :ref:`csharp-replace-one`
 
-.. To learn more about performing the operations mentioned, see the
-.. following guides:
-
-.. TODO create specify a query 
-.. - :ref:`csharp-query-document`
+To learn more about creating query filters, see the :ref:`csharp-specify-query` guide.
 
 API Documentation
 ~~~~~~~~~~~~~~~~~
 
 To learn more about any of the methods or types discussed in this
-guide, see the following API Documentation:
+guide, see the following API documentation:
 
 * `UpdateOne() <{+api-root+}/M_MongoDB_Driver_IMongoCollection_1_UpdateOne.htm>`__
 * `UpdateOneAsync() <{+api-root+}/M_MongoDB_Driver_IMongoCollection_1_UpdateOneAsync.htm>`__
 * `UpdateMany() <{+api-root+}/M_MongoDB_Driver_IMongoCollection_1_UpdateMany.htm>`__
 * `UpdateManyAsync() <{+api-root+}/M_MongoDB_Driver_IMongoCollection_1_UpdateManyAsync.htm>`__
 * `UpdateOptions <{+api-root+}/T_MongoDB_Driver_UpdateOptions.htm>`__
 * `UpdateResult <{+api-root+}/T_MongoDB_Driver_UpdateResult.htm>`__
-
+* `ReplaceOne() <{+api-root+}/M_MongoDB_Driver_IMongoCollection_1_ReplaceOne.htm>`__
+* `ReplaceOneAsync() <{+api-root+}/M_MongoDB_Driver_IMongoCollection_1_ReplaceOneAsync.htm>`__
+* `ReplaceOptions <{+api-root+}/T_MongoDB_Driver_ReplaceOptions.htm>`__
+* `ReplaceOneResult <{+api-root+}/T_MongoDB_Driver_ReplaceOneResult.htm>`__