From 815dd6349b9a1875f2cf73756329535e86e72ff6 Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 10 Jan 2025 10:34:34 -0500 Subject: [PATCH 1/7] DOCSP-46124: sort option for updateone and replaceone --- .../crud/write-operations/modify.txt | 77 +++++++++++++++---- .../fundamentals/code-snippets/Update.java | 26 +++++++ source/whats-new.txt | 4 + 3 files changed, 90 insertions(+), 17 deletions(-) diff --git a/source/fundamentals/crud/write-operations/modify.txt b/source/fundamentals/crud/write-operations/modify.txt index 42c4f6081..ecfbf1da6 100644 --- a/source/fundamentals/crud/write-operations/modify.txt +++ b/source/fundamentals/crud/write-operations/modify.txt @@ -44,7 +44,7 @@ Update Update operations can modify fields and values. They apply changes specified in an update document to one or more documents that match your -query filter. +query filter. The `updateOne() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#updateOne(org.bson.conversions.Bson,org.bson.conversions.Bson)>`__ method changes the first document your query filter matches and the @@ -66,21 +66,53 @@ Update Operation Parameters The ``updateOne()`` and ``updateMany()`` methods both have the following parameters: -- ``query`` specifies a query filter with the criteria to match documents to update in your collection -- ``updateDocument`` specifies the fields and values to modify in the matching document or documents. For this example, we use the :doc:`Updates builder ` to create the update document. +- ``query`` specifies a query filter with the criteria to match + documents to update in your collection. +- ``update`` specifies the fields and values to modify in the matching + document or documents. For this example, we use the :doc:`Updates + builder ` to create the update + document. +- *(Optional)* ``updateOptions`` specifies options that you can set to + customize how the driver performs the update operation. You can create the ``updateDocument`` using an ``Updates`` builder as follows: .. code-block:: java - Bson updateDocument = Updates.operator(field, value); + Bson updateDocument = Updates.operator(, ); See the MongoDB API documentation for a `complete list of -Updates builders and their usage <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Updates.html>`__. +Updates builders and their usage +<{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Updates.html>`__. -Example -``````` +Update One Example +~~~~~~~~~~~~~~~~~~ + +The following example demonstrates how to change the value of the +``color`` field in the first matching document in which the value of +``qty`` is ``0``: + +.. literalinclude:: /includes/fundamentals/code-snippets/Update.java + :language: java + :dedent: + :start-after: begin updateOneExample + :end-before: end updateOneExample + +If multiple documents match the query filter specified in +the ``updateOne()`` method, it replaces the first result. You can +specify a sort in an ``UpdateOptions`` instance to apply an order to +matched documents before the driver performs the replace operation, as +shown in the following code: + +.. literalinclude:: /includes/fundamentals/code-snippets/Update.java + :language: java + :dedent: + :start-after: begin updateoptions + :end-before: end updateoptions + +Update Many Example +~~~~~~~~~~~~~~~~~~~ The paint store receives a fresh shipment and needs to update their inventory. The shipment contains 20 cans of each paint color. @@ -88,8 +120,8 @@ The shipment contains 20 cans of each paint color. To update the inventory, call the ``updateMany()`` method specifying the following: -- A query filter that matches all the colors -- An update document that contains instructions to increment the ``qty`` field by "20" +- A query filter that matches all the colors +- An update document that contains instructions to increment the ``qty`` field by ``20`` .. literalinclude:: /includes/fundamentals/code-snippets/Update.java :language: java @@ -157,10 +189,13 @@ Replace Operation Parameters The ``replaceOne()`` method has the following parameters: - ``query`` specifies a query filter with the criteria to match a document to replace in your collection -- ``replacementDocument`` specifies fields and values of a new ``Document`` object to replace in the matched document +- ``replacement`` specifies fields and values of a new ``Document`` + object to replace in the matched document +- *(Optional)* ``replaceOptions`` specifies options that you can set to + customize how the driver performs the replace operation -Example -``````` +Replace One Example +~~~~~~~~~~~~~~~~~~~ The paint store realizes they must update their inventory again. What they thought was 20 cans of pink paint is actually 25 cans of orange paint. @@ -192,14 +227,23 @@ The following shows the updated document: { "_id": 5, "color": "orange", "qty": 25 } +If multiple documents match the query filter specified in +the ``replaceOne()`` method, it 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 operation, as +shown in the following code: + +.. literalinclude:: /includes/fundamentals/code-snippets/Update.java + :language: java + :dedent: + :start-after: begin replaceoptions + :end-before: end replaceoptions + If zero documents match the query filter in the replace operation, ``replaceOne()`` makes no changes to documents in the collection. See our :doc:`upsert guide ` to learn how to insert a new document instead of replacing one if no -documents match. - -If multiple documents match the query filter specified in -the ``replaceOne()`` method, it replaces the first result. +documents match. .. important:: @@ -208,4 +252,3 @@ the ``replaceOne()`` method, it replaces the first result. For more information about constraints on unique indexes, see :manual:`Unique Indexes ` in the {+mdb-server+} manual. - diff --git a/source/includes/fundamentals/code-snippets/Update.java b/source/includes/fundamentals/code-snippets/Update.java index c146845f7..3b6c0f1b1 100644 --- a/source/includes/fundamentals/code-snippets/Update.java +++ b/source/includes/fundamentals/code-snippets/Update.java @@ -14,6 +14,8 @@ import com.mongodb.client.model.Updates; import com.mongodb.client.result.UpdateResult; +import static com.mongodb.client.model.Sorts.ascending; + public class Update { private final MongoCollection collection; private final MongoClient mongoClient; @@ -41,6 +43,25 @@ public static void main(String [] args){ update.preview(false); } + private void updateOneExample(){ + // Creates a filter and update document to change the value of ``color`` + // begin updateOneExample + Bson filter = Filters.eq("qty", "0"); + Bson update = Updates.set("color", "dandelion"); + + // Updates first document and prints the number of matched and modified documents + UpdateResult result = collection.updateOne(filter, update); + // end updateOneExample + + System.out.println("Matched document count: " + result.getMatchedCount()); + System.out.println("Modified document count: " + result.getModifiedCount()); + + // begin updateoptions + UpdateOptions options = UpdateOptions.sort(ascending("color")); + UpdateResult result = collection.updateOne(filter, document, options); + // end updateoptions + } + private void updateManyExample(){ // Creates a filter and update document to increase the "qty" value of all documents // begin updateManyExample @@ -67,6 +88,11 @@ private void replaceOneExample(){ System.out.println("Matched document count: " + result.getMatchedCount()); System.out.println("Modified document count: " + result.getModifiedCount()); // end replaceOneExample + + // begin replaceoptions + ReplaceOptions options = ReplaceOptions.sort(ascending("qty")); + UpdateResult result = collection.replaceOne(filter, document, options); + // end replaceoptions } private void preview(boolean drop){ diff --git a/source/whats-new.txt b/source/whats-new.txt index 0ededd787..e3109bff8 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -45,6 +45,10 @@ and features: To learn about how to use this type when using the Atlas Vector Search feature, see the TODO add link :ref:`` guide. + .. replacement:: update-replace-example-link + + the :ref:`java-fundamentals-change-document` guide + - Adds a client bulk write API that allows you to perform write operations on multiple databases and collections at once. To learn more about this feature, see the :ref:`java-sync-client-bulk-write` section of the Bulk Operations guide. From 755870744f2635bb867f5d5ac40cf8f3e6385e9c Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 10 Jan 2025 10:36:57 -0500 Subject: [PATCH 2/7] add links --- .../fundamentals/crud/write-operations/modify.txt | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/source/fundamentals/crud/write-operations/modify.txt b/source/fundamentals/crud/write-operations/modify.txt index ecfbf1da6..e79aa5a3f 100644 --- a/source/fundamentals/crud/write-operations/modify.txt +++ b/source/fundamentals/crud/write-operations/modify.txt @@ -73,7 +73,9 @@ parameters: builder ` to create the update document. - *(Optional)* ``updateOptions`` specifies options that you can set to - customize how the driver performs the update operation. + customize how the driver performs the update operation. To learn more + about this type, see the API documentation for `UpdateOptions + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/UpdateOptions.html>`__ You can create the ``updateDocument`` using an ``Updates`` builder as follows: @@ -188,11 +190,14 @@ Replace Operation Parameters The ``replaceOne()`` method has the following parameters: -- ``query`` specifies a query filter with the criteria to match a document to replace in your collection +- ``query`` specifies a query filter with the criteria to match a + document to replace in your collection. - ``replacement`` specifies fields and values of a new ``Document`` - object to replace in the matched document + object to replace in the matched document. - *(Optional)* ``replaceOptions`` specifies options that you can set to - customize how the driver performs the replace operation + customize how the driver performs the replace operation. To learn more + about this type, see the API documentation for `ReplaceOptions + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/ReplaceOptions.html>`__ Replace One Example ~~~~~~~~~~~~~~~~~~~ From c9c96396bc8c5caf158f2a2b11a6a0d775a2c8aa Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 10 Jan 2025 10:44:41 -0500 Subject: [PATCH 3/7] wip --- source/fundamentals/crud/write-operations/modify.txt | 2 +- source/includes/fundamentals/code-snippets/Update.java | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/source/fundamentals/crud/write-operations/modify.txt b/source/fundamentals/crud/write-operations/modify.txt index e79aa5a3f..a21ffc9c9 100644 --- a/source/fundamentals/crud/write-operations/modify.txt +++ b/source/fundamentals/crud/write-operations/modify.txt @@ -183,7 +183,7 @@ instance as follows: .. code-block:: java - collection.replaceOne(query, replacementDocument); + collection.replaceOne(, ); Replace Operation Parameters ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/includes/fundamentals/code-snippets/Update.java b/source/includes/fundamentals/code-snippets/Update.java index 3b6c0f1b1..b19191229 100644 --- a/source/includes/fundamentals/code-snippets/Update.java +++ b/source/includes/fundamentals/code-snippets/Update.java @@ -46,10 +46,10 @@ public static void main(String [] args){ private void updateOneExample(){ // Creates a filter and update document to change the value of ``color`` // begin updateOneExample - Bson filter = Filters.eq("qty", "0"); + Bson filter = Filters.eq("qty", 0); Bson update = Updates.set("color", "dandelion"); - // Updates first document and prints the number of matched and modified documents + // Updates first matching document UpdateResult result = collection.updateOne(filter, update); // end updateOneExample From cfcf5483a2c9fccfb827f9ae3863abfb3914141c Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 10 Jan 2025 10:50:13 -0500 Subject: [PATCH 4/7] wip --- source/fundamentals/crud/write-operations/modify.txt | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/source/fundamentals/crud/write-operations/modify.txt b/source/fundamentals/crud/write-operations/modify.txt index a21ffc9c9..d97f577fa 100644 --- a/source/fundamentals/crud/write-operations/modify.txt +++ b/source/fundamentals/crud/write-operations/modify.txt @@ -56,9 +56,8 @@ You can call the ``updateOne()`` and ``updateMany()`` methods on a .. code-block:: java - collection.updateOne(query, updateDocument); - - collection.updateMany(query, updateDocument); + collection.updateOne(, ); + collection.updateMany(, ); Update Operation Parameters ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -82,7 +81,7 @@ follows: .. code-block:: java - Bson updateDocument = Updates.operator(, ); + Bson update = Updates.operator(, ); See the MongoDB API documentation for a `complete list of Updates builders and their usage From 924ad2eae2ab0c16e7b5a67490c9029391b2b32a Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 10 Jan 2025 11:26:19 -0500 Subject: [PATCH 5/7] NR PR fixes 1 --- source/fundamentals/builders/updates.txt | 4 ++-- .../crud/write-operations/modify.txt | 22 +++++++++---------- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/source/fundamentals/builders/updates.txt b/source/fundamentals/builders/updates.txt index 1ecb923fe..1c213d003 100644 --- a/source/fundamentals/builders/updates.txt +++ b/source/fundamentals/builders/updates.txt @@ -1,3 +1,5 @@ +.. _updates-builders: + ================ Updates Builders ================ @@ -8,8 +10,6 @@ Updates Builders :depth: 2 :class: singlecol -.. _updates-builders: - Overview -------- diff --git a/source/fundamentals/crud/write-operations/modify.txt b/source/fundamentals/crud/write-operations/modify.txt index d97f577fa..6b3f5a145 100644 --- a/source/fundamentals/crud/write-operations/modify.txt +++ b/source/fundamentals/crud/write-operations/modify.txt @@ -68,13 +68,12 @@ parameters: - ``query`` specifies a query filter with the criteria to match documents to update in your collection. - ``update`` specifies the fields and values to modify in the matching - document or documents. For this example, we use the :doc:`Updates - builder ` to create the update - document. + document or documents. The examples in this section use the + :ref:`updates-builders` to create the update document. - *(Optional)* ``updateOptions`` specifies options that you can set to customize how the driver performs the update operation. To learn more about this type, see the API documentation for `UpdateOptions - <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/UpdateOptions.html>`__ + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/UpdateOptions.html>`__. You can create the ``updateDocument`` using an ``Updates`` builder as follows: @@ -83,9 +82,9 @@ follows: Bson update = Updates.operator(, ); -See the MongoDB API documentation for a `complete list of -Updates builders and their usage -<{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Updates.html>`__. +To view a complete list of Updates builders and their usage, see `Updates +<{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Updates.html>`__ +in the API documentation. Update One Example ~~~~~~~~~~~~~~~~~~ @@ -121,8 +120,9 @@ The shipment contains 20 cans of each paint color. To update the inventory, call the ``updateMany()`` method specifying the following: -- A query filter that matches all the colors -- An update document that contains instructions to increment the ``qty`` field by ``20`` +- Query filter that matches all the colors +- Update document that contains instructions to increment the ``qty`` + field by ``20`` .. literalinclude:: /includes/fundamentals/code-snippets/Update.java :language: java @@ -192,11 +192,11 @@ The ``replaceOne()`` method has the following parameters: - ``query`` specifies a query filter with the criteria to match a document to replace in your collection. - ``replacement`` specifies fields and values of a new ``Document`` - object to replace in the matched document. + object to replace the matched document. - *(Optional)* ``replaceOptions`` specifies options that you can set to customize how the driver performs the replace operation. To learn more about this type, see the API documentation for `ReplaceOptions - <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/ReplaceOptions.html>`__ + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/ReplaceOptions.html>`__. Replace One Example ~~~~~~~~~~~~~~~~~~~ From f381e64d9ff466b0f324c8dea3cb38315c98fa8d Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 14 Jan 2025 16:49:22 -0500 Subject: [PATCH 6/7] add bulk info --- .../crud/write-operations/bulk.txt | 38 +++++++++++++++++-- source/whats-new.txt | 3 +- 2 files changed, 37 insertions(+), 4 deletions(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index 959d00468..8940a888a 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -157,10 +157,25 @@ contains an added ``location`` field: :start-after: begin replaceDocumentsExample :end-before: end replaceDocumentsExample +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 +operation, as shown in the following code: + +.. code-block:: java + + ReplaceOptions options = ReplaceOptions.sort(Sorts.ascending("_id")); + For more information about the methods and classes mentioned in this section, see the following resources: -- `ReplaceOneModel <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/ReplaceOneModel.html>`__ API documentation +- `ReplaceOneModel + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/ReplaceOneModel.html>`__ + API documentation +- `ReplaceOptions + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/ReplaceOptions.html>`__ + API documentation - :manual:`Unique indexes ` Server Manual Explanation Update Operation @@ -193,11 +208,28 @@ the ``age`` field in a document where the ``_id`` is ``2``: :start-after: begin updateDocumentsExample :end-before: end updateDocumentsExample +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 replace +operation, as shown in the following code: + +.. code-block:: java + + UpdateOptions options = UpdateOptions.sort(Sorts.ascending("_id")); + For more information about the methods and classes mentioned in this section, see the following resources: -- `UpdateOneModel <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/UpdateOneModel.html>`__ API documentation -- `UpdateManyModel <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/UpdateManyModel.html>`__ API documentation +- `UpdateOneModel + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/UpdateOneModel.html>`__ + API documentation +- `UpdateManyModel + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/UpdateManyModel.html>`__ + API documentation +- `UpdateOptions + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/UpdateOptions.html>`__ + API documentation - :manual:`unique indexes ` Server Manual Explanation Delete Operation diff --git a/source/whats-new.txt b/source/whats-new.txt index 417bf3848..8d272d9f3 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -47,7 +47,8 @@ and features: .. replacement:: update-replace-example-link - the :ref:`java-fundamentals-change-document` guide + the :ref:`java-fundamentals-change-document` and :ref:`java-fundamentals-bulkwrite` + guides - Adds a client bulk write API that allows you to perform write operations on multiple databases and collections at once. To learn more about this feature, see the From ca2caeeb23558ed65e80cf985a97118891d0231c Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 15 Jan 2025 11:06:35 -0500 Subject: [PATCH 7/7] JK tech review 1 --- source/fundamentals/crud/write-operations/bulk.txt | 2 +- source/fundamentals/crud/write-operations/modify.txt | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index 8940a888a..745cada5a 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/fundamentals/crud/write-operations/bulk.txt @@ -211,7 +211,7 @@ the ``age`` field in a document where the ``_id`` is ``2``: 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 replace +an order to matched documents before the driver performs the update operation, as shown in the following code: .. code-block:: java diff --git a/source/fundamentals/crud/write-operations/modify.txt b/source/fundamentals/crud/write-operations/modify.txt index 6b3f5a145..d420d54ad 100644 --- a/source/fundamentals/crud/write-operations/modify.txt +++ b/source/fundamentals/crud/write-operations/modify.txt @@ -100,9 +100,9 @@ The following example demonstrates how to change the value of the :end-before: end updateOneExample If multiple documents match the query filter specified in -the ``updateOne()`` method, it replaces the first result. You can +the ``updateOne()`` method, it 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 replace operation, as +matched documents before the driver performs the update operation, as shown in the following code: .. literalinclude:: /includes/fundamentals/code-snippets/Update.java