DOCSP-41819: replace document

source/includes/write/replace.kt

@@ -0,0 +1,41 @@
+import com.mongodb.client.model.Filters
+import com.mongodb.client.model.Filters.*
+import com.mongodb.client.model.ReplaceOptions
+import com.mongodb.client.model.UpdateOptions
+import com.mongodb.client.model.Updates.*
+import com.mongodb.kotlin.client.MongoClient
+
+// start-data-class
+data class Restaurant(
+    val name: String,
+    val borough: String,
+    val cuisine: String,
+    val owner: String?,
+)
+// end-data-class
+
+fun main() {
+    val uri = "<connection string>"
+
+    val mongoClient = MongoClient.create(uri)
+    val database = mongoClient.getDatabase("sample_restaurants")
+    val collection = database.getCollection<Restaurant>("restaurants")
+
+    // start-replace-one
+    val filter = Filters.eq(Restaurant::name.name, "Primola Restaurant")
+    val replacement = Restaurant(
+        "Frutti Di Mare",
+        "Queens",
+        "Seafood",
+        owner = "Sal Thomas"
+    )
+    val result = collection.replaceOne(filter, replacement)
+    // end-replace-one
+
+    // start-replace-options
+    val opts = ReplaceOptions().upsert(true)
+    val result = collection.replaceOne(filter, replacement, opts)
+    // end-replace-options
+
+}
+

source/write-operations.txt

@@ -24,10 +24,10 @@ Write Data to MongoDB
 
    /write/insert
    /write/update
+   /write/replace
    /write/delete
 
 .. 
-   /write/replace
    /write/bulk-write
    /write/gridfs
 
@@ -135,8 +135,8 @@ collection with a new document:
    :copyable:
    :dedent:
 
-.. To learn more about the ``replace_one()`` method, see the
-.. :ref:`Replace Documents <kotlin-sync-write-replace>` guide.
+To learn more about the ``replaceOne()`` method, see the
+:ref:`Replace Documents <kotlin-sync-write-replace>` guide.
 
 Delete One
 ----------

source/write/replace.txt

@@ -0,0 +1,202 @@
+.. _kotlin-sync-write-replace:
+
+=================
+Replace Documents
+=================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: modify, change, code example
+
+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
+removes all fields and values from a specified document except the
+``_id`` field, and adds new fields and values that you specify. This
+operations differs from an update operation, which changes only
+specified fields in one or more documents.
+
+.. tip:: Learn About Update Operations
+
+   To learn more about update operations, see the
+   :ref:`kotlin-sync-write-update` guide.
+
+Sample Data
+~~~~~~~~~~~
+
+The examples in this guide use the ``sample_restaurants.restaurants`` collection
+from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
+free MongoDB Atlas cluster and load the sample datasets, see the
+:atlas:`Get Started with Atlas </getting-started>` guide.
+
+The documents in this collection are modeled by the following {+language+} data class:
+
+.. literalinclude:: /includes/write/replace.kt
+   :start-after: start-data-class
+   :end-before: end-data-class
+   :language: kotlin
+   :copyable:
+   :dedent:
+
+Replace Operation
+-----------------
+
+You can perform a replace operation in MongoDB by using the
+``replaceOne()`` method. This method removes all fields except the
+``_id`` field from the first document that matches the query filter. It
+then adds the fields and values you specify to the empty document.
+
+Required Parameters
+~~~~~~~~~~~~~~~~~~~
+
+You must pass the following parameters to the ``replaceOne()`` method:
+
+- **Query filter**, which matches which documents to update. To learn
+  more about query filters, see the :ref:`kotlin-sync-specify-query`
+  guide.
+
+- **Replacement document**, which specifies the fields and values that
+  you want to replace the existing fields and values with.
+
+Replace One Document
+--------------------
+
+The following example uses the ``replaceOne()`` method to replace the
+fields and values of a document in which the value of the ``name`` field
+value is ``"Primola Restaurant"``:
+
+.. literalinclude:: /includes/write/replace.kt
+   :start-after: start-replace-one
+   :end-before: end-replace-one
+   :language: kotlin
+   :copyable:
+   :dedent:
+
+.. important::
+
+   The values of ``_id`` fields are immutable. If your replacement document specifies
+   a value for the ``_id`` field, it must be the same as the ``_id`` value of the
+   existing document.
+
+Customize the Replace Operation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``replaceOne()`` method optionally accepts
+a parameter that sets options to configure the replace operation.
+If you don't specify any options, the driver performs the replace
+operation with default settings.
+
+The following table describes the setter methods that you can use to
+configure an ``ReplaceOptions`` instance:
+
+.. list-table::
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Property
+     - Description
+
+   * - ``upsert()``
+     - | Specifies whether the replace operation performs an upsert operation if no 
+         documents match the query filter. For more information, see :manual:`upsert
+         behavior </reference/method/db.collection.replaceOne/#upsert>`
+         in the {+mdb-server+} manual.
+       | Defaults to ``false``
+
+   * - ``bypassDocumentValidation()``
+     - | Specifies whether the update operation bypasses document validation. This lets you 
+         update documents that don't meet the schema validation requirements, if any 
+         exist. For more information about schema validation, see :manual:`Schema
+         Validation </core/schema-validation/#schema-validation>` in the MongoDB
+         Server manual.
+       | Defaults to ``false``.
+
+   * - ``collation()``
+     - | Specifies the kind of language collation to use when sorting
+         results. For more information, see :manual:`Collation </reference/collation/#std-label-collation>`
+         in the {+mdb-server+} manual.
+
+   * - ``hint()``
+     - | Sets the index to use when matching documents. 
+         For more information, see the :manual:`hint statement
+         </reference/method/db.collection.replaceOne/#std-label-replace-one-hint>`
+         in the {+mdb-server+} manual.
+
+   * - ``let()``
+     - | Provides a map of parameter names and values to set top-level
+         variables for the operation. Values must be constant or closed
+         expressions that don't reference document fields.
+
+   * - ``comment()``
+     - | Sets a comment to attach to the operation.
+
+The following code uses the ``replaceOne()`` method to match the first
+document in which the value of the ``name`` field is ``"Pizza Plus"``,
+then replaces the fields with new fields.
+
+Because the ``upsert`` option is set to ``true``, the driver inserts a
+new document that has the fields and values specified in the replacement
+document if the query filter doesn't match any existing documents.
+
+.. literalinclude:: /includes/write/replace.kt
+   :start-after: start-replace-options
+   :end-before: end-replace-options
+   :language: kotlin
+   :copyable:
+   :dedent:
+
+Return Value
+~~~~~~~~~~~~
+
+The ``replaceOne()`` method returns an ``UpdateResult`` 
+object. You can use the following methods to access information from
+an ``UpdateResult`` instance:
+
+.. list-table::
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Property
+     - Description
+
+   * - ``getMatchedCount()``
+     - | Indicates the number of documents that matched the query filter, regardless of
+         how many updates were performed.
+
+   * - ``getModifiedCount()``
+     - | Indicates number of documents modified by the update operation. If an updated
+         document is identical to the original, it is not included in this
+         count.
+
+   * - ``wasAcknowledged()``
+     - | Returns ``true`` if the server acknowledged the result.
+
+   * - ``getUpsertedId()``
+     - | Specifies the ``_id`` value of the document that was upserted
+         in the database, if the driver performed an upsert.
+
+Additional Information 
+----------------------
+
+To view a runnable code example that demonstrates how to replace a
+document, see :ref:`kotlin-sync-write`.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about any of the methods or types discussed in this
+guide, see the following API documentation:
+
+- `replaceOne() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/replace-one.html>`__
+- `UpdateResult <{+core-api+}/com/mongodb/client/result/UpdateResult.html>`__

source/write/update.txt

@@ -209,7 +209,7 @@ an ``UpdateResult`` instance:
 Additional Information 
 ----------------------
 
-To view runnable code examples that demonstrate how to updates documents by
+To view runnable code examples that demonstrate how to update documents by
 using the {+driver-short+}, see :ref:`kotlin-sync-write`.
 
 API Documentation