diff --git a/source/includes/write/replace.kt b/source/includes/write/replace.kt new file mode 100644 index 00000000..e6471166 --- /dev/null +++ b/source/includes/write/replace.kt @@ -0,0 +1,38 @@ +import com.mongodb.client.model.Filters +import com.mongodb.client.model.ReplaceOptions +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 = "" + + val mongoClient = MongoClient.create(uri) + val database = mongoClient.getDatabase("sample_restaurants") + val collection = database.getCollection("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 + +} + diff --git a/source/write-operations.txt b/source/write-operations.txt index 398f3d03..7760534f 100644 --- a/source/write-operations.txt +++ b/source/write-operations.txt @@ -24,11 +24,11 @@ Write Data to MongoDB /write/insert /write/update + /write/replace /write/delete /write/bulk-write .. - /write/replace /write/gridfs Overview @@ -135,8 +135,8 @@ collection with a new document: :copyable: :dedent: -.. To learn more about the ``replace_one()`` method, see the -.. :ref:`Replace Documents ` guide. +To learn more about the ``replaceOne()`` method, see the +:ref:`Replace Documents ` guide. Delete One ---------- diff --git a/source/write/replace.txt b/source/write/replace.txt new file mode 100644 index 00000000..c39ff1a4 --- /dev/null +++ b/source/write/replace.txt @@ -0,0 +1,198 @@ +.. _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. + +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 `. To learn how to create a +free MongoDB Atlas cluster and load the sample datasets, see the +:atlas:`Get Started with Atlas ` 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 or the driver raises a + ``WriteError``. + +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 ` + 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 ` 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 ` + in the {+mdb-server+} manual. + + * - ``hint()`` + - | Sets the index to use when matching documents. + For more information, see the :manual:`hint statement + ` + 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 sets the ``upsert`` option to ``true``, which instructs the +driver to insert 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()`` + - | Returns the number of documents that matched the query filter, regardless of + how many updates were performed. + + * - ``getModifiedCount()`` + - | Returns the 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()`` + - | Returns 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>`__ diff --git a/source/write/update.txt b/source/write/update.txt index 5d53628c..b171bf96 100644 --- a/source/write/update.txt +++ b/source/write/update.txt @@ -183,11 +183,11 @@ an ``UpdateResult`` instance: - Description * - ``getMatchedCount()`` - - | Indicates the number of documents that matched the query filter, regardless of + - | Returns 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 + - | Returns the number of documents modified by the update operation. If an updated document is identical to the original, it is not included in this count. @@ -195,7 +195,7 @@ an ``UpdateResult`` instance: - | Returns ``true`` if the server acknowledged the result. * - ``getUpsertedId()`` - - | Specifies the ``_id`` value of the document that was upserted + - | Returns the ``_id`` value of the document that was upserted in the database, if the driver performed an upsert. .. note:: @@ -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