From 3e8a97383276c597fecbcee7972d2ba88420d8a2 Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 2 Aug 2024 10:28:09 -0400 Subject: [PATCH 1/4] DOCSP-41819: replace document --- source/includes/write/replace.kt | 41 +++++++ source/write-operations.txt | 6 +- source/write/replace.txt | 202 +++++++++++++++++++++++++++++++ source/write/update.txt | 2 +- 4 files changed, 247 insertions(+), 4 deletions(-) create mode 100644 source/includes/write/replace.kt create mode 100644 source/write/replace.txt diff --git a/source/includes/write/replace.kt b/source/includes/write/replace.kt new file mode 100644 index 00000000..b7eca842 --- /dev/null +++ b/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 = "" + + 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 cabd4012..99c2e226 100644 --- a/source/write-operations.txt +++ b/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 ` 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..68abe73c --- /dev/null +++ b/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 `. 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. + +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 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>`__ diff --git a/source/write/update.txt b/source/write/update.txt index 8d2c32d4..4558bd91 100644 --- a/source/write/update.txt +++ b/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 From 5c8cd2a2d56415bcbf12c4a721b58461f9d88a99 Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 2 Aug 2024 11:23:46 -0400 Subject: [PATCH 2/4] AS PR fixes 1 --- source/write/replace.txt | 30 +++++++++++++----------------- source/write/update.txt | 6 +++--- 2 files changed, 16 insertions(+), 20 deletions(-) diff --git a/source/write/replace.txt b/source/write/replace.txt index 68abe73c..bf72d65a 100644 --- a/source/write/replace.txt +++ b/source/write/replace.txt @@ -27,10 +27,8 @@ removes all fields and values from a specified document except the 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. +To learn more about update operations, see the +:ref:`kotlin-sync-write-update` guide. Sample Data ~~~~~~~~~~~ @@ -85,9 +83,10 @@ value is ``"Primola Restaurant"``: .. 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. + 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -141,13 +140,10 @@ configure an ``ReplaceOptions`` instance: * - ``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. +The following code sets the ``upsert`` option ``true``, instructing 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 @@ -171,11 +167,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. @@ -183,7 +179,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. Additional Information diff --git a/source/write/update.txt b/source/write/update.txt index 4558bd91..8cf627f9 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:: From f6207f0abe7719c002a41550326d88bec5fe2b36 Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 2 Aug 2024 11:24:43 -0400 Subject: [PATCH 3/4] fix --- source/write/replace.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/write/replace.txt b/source/write/replace.txt index bf72d65a..c39ff1a4 100644 --- a/source/write/replace.txt +++ b/source/write/replace.txt @@ -140,7 +140,7 @@ configure an ``ReplaceOptions`` instance: * - ``comment()`` - | Sets a comment to attach to the operation. -The following code sets the ``upsert`` option ``true``, instructing the +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: From 67132c280f2fdeb8419d4023b52977e2259d0b57 Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 7 Aug 2024 11:14:34 -0400 Subject: [PATCH 4/4] remove unused import --- source/includes/write/replace.kt | 3 --- 1 file changed, 3 deletions(-) diff --git a/source/includes/write/replace.kt b/source/includes/write/replace.kt index b7eca842..e6471166 100644 --- a/source/includes/write/replace.kt +++ b/source/includes/write/replace.kt @@ -1,8 +1,5 @@ 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