DOCSP-46772: sort option for client bw - updateone & replaceone (#85)

* DOCSP-46772: sort option for client bw - updateone & replaceone

* wip

Author: rustagir

source/includes/write/client-bulk-write.kt

@@ -1,5 +1,7 @@
 import com.mongodb.MongoNamespace
+import com.mongodb.client.model.Filters
 import com.mongodb.client.model.Filters.eq
+import com.mongodb.client.model.Updates
 import com.mongodb.client.model.bulk.ClientBulkWriteOptions
 import com.mongodb.client.model.bulk.ClientBulkWriteResult
 import com.mongodb.client.model.bulk.ClientNamespacedWriteModel
@@ -12,11 +14,13 @@ data class Restaurant(
     val name: String,
     val borough: String,
     val cuisine: String,
+    val stars: Int? = null,
 )
 
 data class Movie(
     val title: String,
-    val year: Int
+    val year: Int,
+    val seen: Boolean? = null,
 )
 // end-data-classes
 
@@ -39,6 +43,22 @@ fun main() {
         )
     // end-insert-models
 
+    // start-update-models
+    val restaurantUpdate = ClientNamespacedWriteModel
+        .updateOne(
+            MongoNamespace("sample_restaurants", "restaurants"),
+            Filters.eq(Restaurant::name.name, "Villa Berulia"),
+            Updates.inc(Restaurant::stars.name, 1)
+        )
+
+    val movieUpdate = ClientNamespacedWriteModel
+        .updateMany(
+            MongoNamespace("sample_mflix", "movies"),
+            Filters.eq(Movie::title.name, "Carrie"),
+            Updates.set(Movie::seen.name, true)
+        )
+    // end-update-models
+
     // start-replace-models
     val restaurantReplacement = ClientNamespacedWriteModel
         .replaceOne(
@@ -102,7 +122,7 @@ fun main() {
         )
     )
 
-    val result= mongoClient
+    val result = mongoClient
         .bulkWrite(bulkOps, options)
     // end-options
 }

source/whats-new.txt

@@ -12,6 +12,7 @@ What's New
 
 Learn what's new in:
 
+* :ref:`Version 5.4 <kotlin-sync-version-5.4>`
 * :ref:`Version 5.3 <kotlin-sync-version-5.3>`
 * :ref:`Version 5.2 <kotlin-sync-version-5.2>`
 * :ref:`Version 5.1.3 <kotlin-sync-version-5.1.3>`
@@ -20,6 +21,22 @@ Learn what's new in:
 * :ref:`Version 5.1 <kotlin-sync-version-5.1>`
 * :ref:`Version 5.0 <kotlin-sync-version-5.0>`
 
+.. _kotlin-sync-version-5.4:
+
+What's New in 5.4
+-----------------
+
+The 5.4 driver release includes the following changes, fixes,
+and features:
+
+.. sharedinclude:: dbx/jvm/v5.4-wn-items.rst
+
+   .. replacement:: sort-option-link
+
+      the :ref:`kotlin-sync-client-bulk-write-update` and
+      :ref:`kotlin-sync-client-bulk-write-replace` sections of the Bulk Write
+      Operations guide
+
 .. _kotlin-sync-version-5.3:
 
 What's New in 5.3

source/write/bulk-write.txt

@@ -55,7 +55,7 @@ Atlas </getting-started>` guide.
 The documents in these collections are modeled by the following
 {+language+} data classes:
 
-.. literalinclude:: /includes/write/bulk.kt
+.. literalinclude:: /includes/write/client-bulk-write.kt
    :start-after: start-data-classes
    :end-before: end-data-classes
    :language: kotlin
@@ -138,7 +138,7 @@ The following example creates an instance of ``UpdateOneModel``:
 If multiple documents match the query filter specified in
 the ``UpdateOneModel`` instance, the operation updates the first
 result. You can specify a sort in an ``UpdateOptions`` instance to apply
-an order to matched documents before the driver performs the update
+an order to matched documents before the server performs the update
 operation, as shown in the following code:
 
 .. code-block:: kotlin
@@ -181,7 +181,7 @@ The following example creates an instance of ``ReplaceOneModel``:
 If multiple documents match the query filter specified in
 the ``ReplaceOneModel`` instance, the operation replaces the first
 result. You can specify a sort in a ``ReplaceOptions`` instance to apply
-an order to matched documents before the driver performs the replace
+an order to matched documents before the server performs the replace
 operation, as shown in the following code:
 
 .. code-block:: kotlin
@@ -467,8 +467,8 @@ Insert Operations
 ~~~~~~~~~~~~~~~~~
 
 This example shows how to create models that contain instructions to
-insert two documents. One document is inserted into the ``db.people``
-collection, and the other document is inserted into the ``db.things`` collection.
+insert two documents. One document is inserted into the ``sample_restaurants.restaurants``
+collection, and the other document is inserted into the ``sample_mflix.movies`` collection.
 The ``MongoNamespace`` instance defines the target database and collection that 
 each write operation applies to.
 
@@ -479,11 +479,49 @@ each write operation applies to.
    :copyable:
    :dedent:
 
+.. _kotlin-sync-client-bulk-write-update:
+
+Update Operation
+~~~~~~~~~~~~~~~~
+
+The following example shows how to use the ``bulkWrite()`` method to update
+existing documents in the ``sample_restaurants.restaurants`` and
+``sample_mflix.movies`` collections:
+
+.. literalinclude:: /includes/write/client-bulk-write.kt
+   :start-after: start-update-models
+   :end-before: end-update-models
+   :language: kotlin
+   :copyable:
+   :dedent:
+
+This example increments the value of the ``stars`` field by ``1`` in the
+document that has a ``name`` value of ``"Villa Berulia"`` in the
+``restaurants`` collection. It also sets the value of the ``seen`` field
+to ``true`` in all documents that have a ``title`` value of ``"Carrie"``
+in the ``movies`` collection.
+
+If multiple documents match the query filter specified in
+a ``ClientNamespacedUpdateOneModel`` instance, the operation updates the
+first result. You can specify a sort order in a `ClientUpdateOneOptions
+<{+core-api+}/com/mongodb/client/model/bulk/ClientUpdateOneOptions.html>`__
+instance to apply an order to matched documents before the server
+performs the update operation, as shown in the following code:
+
+.. code-block:: kotlin
+
+   val options =  ClientUpdateOneOptions
+       .clientUpdateOneOptions()
+       .sort(Sorts.ascending("_id"))
+
+.. _kotlin-sync-client-bulk-write-replace:
+
 Replace Operations
 ~~~~~~~~~~~~~~~~~~
 
 The following example shows how to create models to replace
-existing documents in the ``db.people`` and ``db.things`` collections:
+existing documents in the ``sample_restaurants.restaurants`` and
+``sample_mflix.movies`` collections:
 
 .. literalinclude:: /includes/write/client-bulk-write.kt
    :start-after: start-replace-models
@@ -493,9 +531,22 @@ existing documents in the ``db.people`` and ``db.things`` collections:
    :dedent:
 
 After this example runs successfully, the document that has an ``_id`` value of ``1`` 
-in the ``people`` collection is replaced with a new document. The document in 
-the ``things`` collection that has an ``_id`` value of ``1`` 
-is replaced with a new document.
+in the ``restaurants`` collection is replaced with a new document. The document in 
+the ``movies`` collection that has an ``_id`` value of ``1`` 
+is also replaced with a new document.
+
+If multiple documents match the query filter specified in
+a ``ClientNamespacedReplaceOneModel`` instance, the operation replaces the
+first result. You can specify a sort order in a `ClientReplaceOneOptions
+<{+core-api+}/com/mongodb/client/model/bulk/ClientReplaceOneOptions.html>`__
+instance to apply an order to matched documents before the driver
+performs the replace operation, as shown in the following code:
+
+.. code-block:: kotlin
+
+   val options =  ClientReplaceOneOptions
+       .clientReplaceOneOptions()
+       .sort(Sorts.ascending("_id"))
 
 Perform the Bulk Operation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~