replace.txt

.. _csharp-replace-operation:
.. _csharp-replace-documents:

=================
Replace Documents
=================

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 2
   :class: singlecol

.. facet::
   :name: genre
   :values: reference

.. meta::
   :keywords: replace, synchronous, asynchronous

Overview
--------

In this guide, you can learn how to use the {+driver-short+} to replace
documents in a MongoDB collection.

The {+driver-short+} provides the ``ReplaceOne()`` and ``ReplaceOneAsync()`` methods.
These methods remove all fields (except the ``_id`` field) from the first document that
matches the search criteria, then insert the fields and values you specify into the 
document.

.. include:: /includes/method-overloads.rst

.. include:: /includes/atlas-sample-data.rst

Replace One Document
--------------------

To replace a document in a collection, call the ``ReplaceOne()`` or ``ReplaceOneAsync()``
method. These methods accept the following parameters:

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Parameter
     - Description

   * - ``filter``
     - A *query filter* that specifies the document to replace. You can use the
       ``Builders`` class to create a query filter. For more information about
       query filters, see the
       :manual:`{+mdb-server+} manual </core/document/#query-filter-documents>`.

       **Data Type:** `FilterDefinition<TDocument> <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.FilterDefinition-1.html>`__

   * - ``replacement``
     - 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. 

       **Data Type:** ``TDocument`` 

   * - ``options``
     - *Optional.* An instance of the ``ReplaceOptions`` class that specifies the
       configuration for the replace operation. The default value is ``null``.

       **Data Type:** `ReplaceOptions <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ReplaceOptions.html>`__

   * - ``cancellationToken``
     - *Optional.* A token that you can use to cancel the operation.

       **Data type**: `CancellationToken <https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken>`__

The following code example demonstrates how to perform a replace operation. The
code performs the following steps:

1. Creates a query filter by using the ``Builders`` class. The filter matches all
   documents where the ``cuisine`` field has the value ``"Pizza"``.
#. Creates a new ``Restaurant`` object.
#. Calls the ``ReplaceOne()`` method on the ``restaurants`` collection. This operation
   finds the first matching document in the collection and replaces it with the newly created
   document.

Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the
corresponding code.

.. tabs::

   .. tab:: Synchronous
      :tabid: sync

      .. literalinclude:: /includes/code-examples/replace-one/ReplaceOne.cs
         :language: csharp
         :copyable: true
         :dedent:
         :start-after: // start-replace-one
         :end-before: // end-replace-one

   .. tab:: Asynchronous
      :tabid: async

      .. literalinclude:: /includes/code-examples/replace-one/ReplaceOneAsync.cs
         :language: csharp
         :copyable: true
         :dedent:
         :start-after: // start-replace-one-async
         :end-before: // end-replace-one-async

.. 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. 
   
   If your replacement document does not specify a value for the ``_id`` field,
   you can add the ``[BsonIgnoreIfDefault]`` attribute to the ``_id`` field in
   your Plain Old CLR/Class Object (POCO). Use ``[BsonIgnoreIfDefault]`` if the
   ``_id`` field in your POCO is of the ``ObjectId`` type.
   
   The following example shows how to add this attribute:

   .. code-block:: csharp

      public class Restaurant
      {
          [BsonIgnoreIfDefault]
          public ObjectId Id { get; set; }

          // Other properties
      }

Customize the Replace Operation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The ``ReplaceOne()`` and ``ReplaceOneAsync()`` methods optionally accept a
``ReplaceOptions`` object as a parameter, which represents options you can use to
configure the replace operation.

The ``ReplaceOptions`` class contains 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 {+mdb-server+} manual </core/schema-validation/#schema-validation>`
       for more information on schema validation.

       **Data Type:** ``bool?``

   * - ``Collation``
     - Specifies the kind of language collation to use when sorting
       results. See :manual:`the {+mdb-server+} manual </reference/collation/#std-label-collation>`
       for more information on collation.

       **Data Type:** `Collation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Collation.html>`__

   * - ``Comment``
     - Gets or sets the user-provided comment for the operation. 
       See :manual:`the {+mdb-server+} manual</reference/command/update/#command-fields>`
       for more information.

       **Data Type:** `BsonValue <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.BsonValue.html>`__

   * - ``Hint``
     - Gets or sets the index to use to scan for documents. 
       See :manual:`the {+mdb-server+} manual</reference/command/update/#std-label-update-command-hint>`
       for more information.

       **Data Type:** `BsonValue <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.BsonValue.html>`__

   * - ``IsUpsert``
     - Specifies whether the replace operation performs an upsert operation if no 
       documents match the query filter. 
       See :manual:`the {+mdb-server+} manual </reference/command/update/#std-label-update-command-upsert>`
       for more information.

       **Data Type:** ``bool``

   * - ``Let``
     - Gets or sets the let document. 
       See :manual:`the {+mdb-server+} manual </reference/command/update/#std-label-update-let-syntax>`
       for more information.

       **Data Type:** `BsonDocument <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.BsonDocument.html>`__

The following example performs the same steps as the preceding example, but also uses
the ``BypassDocumentValidation`` option to bypass any schema validation requirements.
Select  the :guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding
code.

.. tabs::

   .. tab:: Synchronous
      :tabid: sync

      .. literalinclude:: /includes/code-examples/replace-one/ReplaceOne.cs
         :language: csharp
         :copyable: true
         :dedent:
         :start-after: // start-replace-one-sync-with-options
         :end-before: // end-replace-one-sync-with-options

   .. tab:: Asynchronous
      :tabid: async

      .. literalinclude:: /includes/code-examples/replace-one/ReplaceOneAsync.cs
         :language: csharp
         :copyable: true
         :dedent:
         :start-after: // start-replace-one-async-with-options
         :end-before: // end-replace-one-async-with-options

Return Value
~~~~~~~~~~~~

The ``ReplaceOne()`` method returns a ``ReplaceOneResult`` 
object, and the ``ReplaceOneAsync()`` method returns a ``Task<ReplaceOneResult>`` object.
The ``ReplaceOneResult`` class contains the following properties:

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Property
     - Description

   * - ``IsAcknowledged``
     - Indicates whether the replace operation was acknowledged by MongoDB.

       **Data Type:** ``bool``
   
   * - ``IsModifiedCountAvailable``
     - Indicates whether you can read the count of replaced records on the
       ``ReplaceOneResult``.

       **Data Type:** ``bool``

   * - ``MatchedCount``
     - The number of documents that matched the query filter, regardless of
       whether one was replaced. 

       **Data Type:** ``long``

   * - ``ModifiedCount``
     - The number of documents replaced by the replace operation. 

       **Data Type:** ``long``

   * - ``UpsertedId``
     - The ID of the document that was upserted in the database, if the driver
       performed an upsert.

       **Data Type:** `BsonValue <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.BsonValue.html>`__

API Documentation
~~~~~~~~~~~~~~~~~

To learn more about any of the methods and classes used on this page,
see the following API documentation:

* `ReplaceOne() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.ReplaceOne.html>`__
* `ReplaceOneAsync() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.ReplaceOneAsync.html>`__
* `ReplaceOptions <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ReplaceOptions.html>`__
* `ReplaceOneResult <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ReplaceOneResult.html>`__