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/bulk.txt b/source/fundamentals/crud/write-operations/bulk.txt index 959d00468..745cada5a 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 update +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/fundamentals/crud/write-operations/modify.txt b/source/fundamentals/crud/write-operations/modify.txt index 42c4f6081..d420d54ad 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 @@ -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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -66,21 +65,54 @@ 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. 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>`__. You can create the ``updateDocument`` using an ``Updates`` builder as follows: .. code-block:: java - Bson updateDocument = Updates.operator(field, value); + Bson update = Updates.operator(, ); + +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 +~~~~~~~~~~~~~~~~~~ + +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 -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>`__. +If multiple documents match the query filter specified in +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 update operation, as +shown in the following code: -Example -``````` +.. 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,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 @@ -149,18 +182,24 @@ instance as follows: .. code-block:: java - collection.replaceOne(query, replacementDocument); + collection.replaceOne(, ); 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 +- ``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 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>`__. -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 +231,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 +256,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..b19191229 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 matching document + 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 e5c95c0c3..8d272d9f3 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -45,6 +45,11 @@ and features: To learn about how to use this type when using the Atlas Vector Search feature, see the :ref:`java-atlas-vector-search` guide. + .. replacement:: update-replace-example-link + + 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 :ref:`java-sync-client-bulk-write` section of the Bulk Operations guide.