From 92192af727b6c46a8af47dc631f91b31f70748fc Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 28 Aug 2024 15:20:20 -0400 Subject: [PATCH 1/3] DOCSP-41968: Update documents --- source/includes/write/update.php | 45 ++++++ source/index.txt | 1 + source/write.txt | 11 ++ source/write/update.txt | 227 +++++++++++++++++++++++++++++++ 4 files changed, 284 insertions(+) create mode 100644 source/includes/write/update.php create mode 100644 source/write.txt create mode 100644 source/write/update.txt diff --git a/source/includes/write/update.php b/source/includes/write/update.php new file mode 100644 index 00000000..2aee12b7 --- /dev/null +++ b/source/includes/write/update.php @@ -0,0 +1,45 @@ +sample_restaurants->restaurants; +// end-db-coll + +// Updates the "name" value of a document from "Bagels N Buns" to "2 Bagels 2 Buns" +// start-update-one +$result = $collection->updateOne( + ['name' => 'Bagels N Buns'], + ['$set' => ['name' => '2 Bagels 2 Buns']] +); +// end-update-one + +// Updates the "cuisine" value of documents from "Pizza" to "Pasta" +// start-update-many +$result = $collection->updateMany( + ['cuisine' => 'Pizza'], + ['$set' => ['cuisine' => 'Pasta']] +); +// end-update-many + +// Updates the "borough" value of matching documents and inserts a document if none match +// start-update-options +$result = $collection->updateMany( + ['borough' => 'Manhattan'], + ['$set' => ['borough' => 'Manhattan (north)']], + ['upsert' => true] +); +// end-update-options + +// Updates the "name" value of matching documents and prints the number of updates +// start-update-result +$result = $collection->updateMany( + ['name' => 'Dunkin\' Donuts'], + ['$set' => ['name' => 'Dunkin\'']] +); +echo 'Modified documents: ' . $result->getModifiedCount(); +// end-update-result + diff --git a/source/index.txt b/source/index.txt index 38ff991f..7805e642 100644 --- a/source/index.txt +++ b/source/index.txt @@ -12,6 +12,7 @@ MongoDB PHP Library Get Started /read + /write /tutorial /upgrade /reference diff --git a/source/write.txt b/source/write.txt new file mode 100644 index 00000000..9053d5a4 --- /dev/null +++ b/source/write.txt @@ -0,0 +1,11 @@ +.. _php-write: + +===================== +Write Data to MongoDB +===================== + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /write/update \ No newline at end of file diff --git a/source/write/update.txt b/source/write/update.txt new file mode 100644 index 00000000..f1555d28 --- /dev/null +++ b/source/write/update.txt @@ -0,0 +1,227 @@ +.. _php-write-update: + +================ +Update Documents +================ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: modify, change, bulk, code example + +Overview +-------- + +In this guide, you can learn how to use the {+php-library+} to update +documents in a MongoDB collection. You can call the ``MongoDB\Collection::updateOne()`` +method to update a single document or the ``MongoDB\Collection::updateMany()`` +method to update multiple documents. + +Sample Data +~~~~~~~~~~~ + +The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants`` +database from the :atlas:`Atlas sample datasets `. To access this collection +from your PHP application, instantiate a ``MongoDB\Client`` that connects to an Atlas cluster +and assign the following value to your ``collection`` variable: + +.. literalinclude:: /includes/write/update.php + :language: php + :dedent: + :start-after: start-db-coll + :end-before: end-db-coll + +To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the +:atlas:`Get Started with Atlas ` guide. + +Update Operations +----------------- + +You can perform update operations in MongoDB by using the following methods: + +- ``MongoDB\Collection::updateOne()``, which updates *the first document* that + matches the search criteria +- ``MongoDB\Collection::updateMany()``, which updates *all documents* that match + the search criteria + +Each update method requires the following parameters: + +- **Query filter** document: Specifies which documents to update. For + more information about query filters, see the + :manual:`Query Filter Documents section ` in + the {+mdb-server+} manual. + +- **Update** document: Specifies the **update operator**, or the kind of update to + perform, and the fields and values to change. For a list of update operators + and their usage, see the :manual:`Field Update Operators guide + ` in the {+mdb-server+} manual. + +Update One Document +~~~~~~~~~~~~~~~~~~~ + +The following example uses the ``updateOne()`` method to update the ``name`` +value of a document in the ``restaurants`` collection from ``'Bagels N Buns'`` +to ``'2 Bagels 2 Buns'``: + +.. literalinclude:: /includes/write/update.php + :start-after: start-update-one + :end-before: end-update-one + :language: php + :dedent: + +Update Many Documents +~~~~~~~~~~~~~~~~~~~~~ + +The following example uses the ``updateMany()`` method to update all documents +that have a ``cuisine`` value of ``'Pizza'``. After the update, the documents have +a ``cuisine`` value of ``'Pasta'``. + +.. literalinclude:: /includes/write/update.php + :start-after: start-update-many + :end-before: end-update-many + :language: php + :dedent: + +Customize the Update Operation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can modify the behavior of the ``updateOne()`` and ``updateMany()`` methods by +passing an array that specifies option values as a parameter. The following table +describes some options you can set in the array: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Option + - Description + + * - ``upsert`` + - | Specifies whether the update operation performs an upsert operation if no + documents match the query filter. For more information, see the :manual:`upsert + statement ` + 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. + + * - ``arrayFilters`` + - | Specifies which array elements an update applies to if the operation modifies + array fields. + + * - ``hint`` + - | Sets the index to scan for documents. + For more information, see the :manual:`hint statement ` + in the {+mdb-server+} manual. + + * - ``writeConcern`` + - | Sets the write concern for the operation. + For more information, see :manual:`Write Concern ` + in the {+mdb-server+} manual. + + * - ``let`` + - | Specifies a document with a list of values to improve operation readability. + Values must be constant or closed expressions that don't reference document + fields. For more information, see the :manual:`let statement + ` in the + {+mdb-server+} manual. + + * - ``comment`` + - | A comment to attach to the operation. For more information, see the :manual:`insert command + fields ` guide in the + {+mdb-server+} manual for more information. + +The following example uses the ``updateMany()`` method to find all documents that +have ``borough`` value of ``'Manhattan'``. It then updates the ``borough`` value +in these documents to ``'Manhattan (north)''``. Because the ``upsert`` option is +set to ``true``, the {+php-library+} inserts a new document if the query filter doesn't +match any existing documents. + +.. literalinclude:: /includes/write/update.php + :start-after: start-update-options + :end-before: end-update-options + :language: php + :dedent: + +Return Value +~~~~~~~~~~~~ + +The ``updateOne()`` and ``updateMany()`` methods return an instance of +the ``MongoDB\UpdateResult`` class. This class contains the following +member functions: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Function + - Description + + * - ``getMatchedCount()`` + - | Returns the number of documents that matched the query filter, regardless of + how many were updated. + + * - ``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. + + * - ``isAcknowledged()`` + - | Returns a boolean indicating whether the write operation was acknowledged. + + * - ``getUpsertedCount()`` + - | Returns the number of document that were upserted into the database. + + * - ``getUpsertedId()`` + - | Returns the ID of the document that was upserted in the database, if the driver + performed an upsert. + +The following example uses the ``updateMany()`` method to update the ``name`` field +of matching documents from ``'Dunkin' Donuts'`` to ``'Dunkin''``. It calls the +``getModifiedCount()`` member function to print the number of modified documents: + +.. io-code-block:: + + .. input:: /includes/write/update.php + :start-after: start-update-result + :end-before: end-update-result + :language: php + :dedent: + + .. output:: + + Modified documents: 206 + +Additional Information +---------------------- + +To learn more about creating query filters, see the :ref:`php-specify-query` guide. + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about any of the methods or types discussed in this +guide, see the following API documentation: + +- `MongoDB\\Collection::updateOne() <{+api+}/method/MongoDBCollection-updateOne>`__ +- `MongoDB\\Collection::updateMany() <{+api+}/method/MongoDBCollection-updateMany>`__ +- `MongoDB\\UpdateResult <{+api+}/class/MongoDBUpdateResult>`__ \ No newline at end of file From 10396b4544ecbaa114109ebf96d7cb7a3f9ec6ab Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 28 Aug 2024 15:21:22 -0400 Subject: [PATCH 2/3] snooty fix --- snooty.toml | 1 - 1 file changed, 1 deletion(-) diff --git a/snooty.toml b/snooty.toml index e30bbbc3..a77d00d6 100644 --- a/snooty.toml +++ b/snooty.toml @@ -28,5 +28,4 @@ php-library = "MongoDB PHP Library" php-library = "MongoDB PHP Library" driver-short = "PHP library" mdb-server = "MongoDB Server" -driver-short = "PHP library" api = "https://www.mongodb.com/docs/php-library/current/reference" From e40e9e784395c4cc34410887cd12a85f61afafa9 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 28 Aug 2024 15:25:27 -0400 Subject: [PATCH 3/3] edits --- source/write/update.txt | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/source/write/update.txt b/source/write/update.txt index f1555d28..e07bde61 100644 --- a/source/write/update.txt +++ b/source/write/update.txt @@ -148,11 +148,11 @@ describes some options you can set in the array: * - ``comment`` - | A comment to attach to the operation. For more information, see the :manual:`insert command fields ` guide in the - {+mdb-server+} manual for more information. + {+mdb-server+} manual. The following example uses the ``updateMany()`` method to find all documents that have ``borough`` value of ``'Manhattan'``. It then updates the ``borough`` value -in these documents to ``'Manhattan (north)''``. Because the ``upsert`` option is +in these documents to ``'Manhattan (north)'``. Because the ``upsert`` option is set to ``true``, the {+php-library+} inserts a new document if the query filter doesn't match any existing documents. @@ -200,6 +200,7 @@ of matching documents from ``'Dunkin' Donuts'`` to ``'Dunkin''``. It calls the ``getModifiedCount()`` member function to print the number of modified documents: .. io-code-block:: + :copyable: .. input:: /includes/write/update.php :start-after: start-update-result @@ -208,7 +209,8 @@ of matching documents from ``'Dunkin' Donuts'`` to ``'Dunkin''``. It calls the :dedent: .. output:: - + :visible: false + Modified documents: 206 Additional Information