From 063a59b609c6b76703eeec2dbf2ada8a4ba3fc86 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 20 May 2025 09:16:58 -0400 Subject: [PATCH 01/12] DOCSP-49150: bulkWrite docs + api --- .../includes/extracts-bulkwriteexception.yaml | 15 +- source/includes/extracts-error.yaml | 11 +- source/includes/write/bulk-write.php | 120 +++++- source/reference.txt | 1 + .../class/MongoDBBulkWriteCommandResult.txt | 61 +++ source/reference/class/MongoDBClient.txt | 4 +- .../class/MongoDBClientBulkWrite.txt | 45 +++ .../method/MongoDBClient-bulkWrite.txt | 100 +++++ ...DBClientBulkWrite-createWithCollection.txt | 85 ++++ .../MongoDBClientBulkWrite-deleteMany.txt | 73 ++++ .../MongoDBClientBulkWrite-deleteOne.txt | 73 ++++ .../MongoDBClientBulkWrite-insertOne.txt | 53 +++ .../MongoDBClientBulkWrite-replaceOne.txt | 89 ++++ .../MongoDBClientBulkWrite-updateMany.txt | 96 +++++ .../MongoDBClientBulkWrite-updateOne.txt | 98 +++++ .../MongoDBClientBulkWrite-withCollection.txt | 50 +++ source/reference/result-classes.txt | 1 + source/write/bulk-write.txt | 380 ++++++++++++++++-- source/write/transaction.txt | 8 + 19 files changed, 1308 insertions(+), 55 deletions(-) create mode 100644 source/reference/class/MongoDBBulkWriteCommandResult.txt create mode 100644 source/reference/class/MongoDBClientBulkWrite.txt create mode 100644 source/reference/method/MongoDBClient-bulkWrite.txt create mode 100644 source/reference/method/MongoDBClientBulkWrite-createWithCollection.txt create mode 100644 source/reference/method/MongoDBClientBulkWrite-deleteMany.txt create mode 100644 source/reference/method/MongoDBClientBulkWrite-deleteOne.txt create mode 100644 source/reference/method/MongoDBClientBulkWrite-insertOne.txt create mode 100644 source/reference/method/MongoDBClientBulkWrite-replaceOne.txt create mode 100644 source/reference/method/MongoDBClientBulkWrite-updateMany.txt create mode 100644 source/reference/method/MongoDBClientBulkWrite-updateOne.txt create mode 100644 source/reference/method/MongoDBClientBulkWrite-withCollection.txt diff --git a/source/includes/extracts-bulkwriteexception.yaml b/source/includes/extracts-bulkwriteexception.yaml index 6276458e..3791eec8 100644 --- a/source/includes/extracts-bulkwriteexception.yaml +++ b/source/includes/extracts-bulkwriteexception.yaml @@ -2,7 +2,7 @@ ref: bulkwriteexception-result content: | If a :php:`MongoDB\Driver\Exception\BulkWriteException ` is thrown, users should call - :php:`getWriteResult() ` and + :php:`getWriteResult() ` and inspect the returned :php:`MongoDB\Driver\WriteResult ` object to determine the nature of the error. @@ -11,6 +11,18 @@ content: | too long). Alternatively, a write operation may have failed outright (e.g. unique key violation). --- +ref: bulkwriteexception-client-result +content: | + If a :php:`MongoDB\Driver\Exception\BulkWriteCommandException + ` is thrown, users should call + :php:`getWriteErrors() ` and + inspect the information in the returned array to determine the nature of the error. + + For example, a write operation may have been successfully applied to the + primary server but failed to satisfy the write concern. Alternatively, a + write operation may have failed outright, for example for violating the + unique key constraint. +--- ref: bulkwriteexception-ordered content: | In the case of a bulk write, the result may indicate multiple successful write @@ -18,4 +30,3 @@ content: | operations may have succeeded before the first error was encountered and the exception thrown. If the ``ordered`` option is ``false``, multiple errors may have been encountered. -... diff --git a/source/includes/extracts-error.yaml b/source/includes/extracts-error.yaml index c4d8afa5..64581a99 100644 --- a/source/includes/extracts-error.yaml +++ b/source/includes/extracts-error.yaml @@ -3,7 +3,15 @@ content: | :php:`MongoDB\Driver\Exception\BulkWriteException ` for errors related to the write operation. Users should inspect the value returned by :php:`getWriteResult() - ` to determine the nature of the + ` to determine the nature of the + error. +--- +ref: error-driver-client-bulkwriteexception +content: | + :php:`MongoDB\Driver\Exception\BulkWriteCommandException + ` for errors related to the write + operation. Users should inspect the value returned by :php:`getWriteErrors() + ` to determine the nature of the error. --- ref: error-driver-invalidargumentexception @@ -49,4 +57,3 @@ ref: error-gridfs-corruptfileexception content: | :phpclass:`MongoDB\GridFS\Exception\CorruptFileException` if the file's metadata or chunk documents contain unexpected or invalid data. -... diff --git a/source/includes/write/bulk-write.php b/source/includes/write/bulk-write.php index a3543a22..4ca84dbb 100644 --- a/source/includes/write/bulk-write.php +++ b/source/includes/write/bulk-write.php @@ -5,24 +5,22 @@ $uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your Atlas URI that connects to the sample dataset'); $client = new MongoDB\Client($uri); -// start-db-coll -$collection = $client->sample_restaurants->restaurants; -// end-db-coll - // start-run-bulk -$result = $collection->bulkWrite( +$restaurantCollection = $client->sample_restaurants->restaurants; + +$result = $restaurantCollection->bulkWrite( [ [ 'insertOne' => [ - ['name' => 'Mongo\'s Deli'], - ['cuisine' => 'Sandwiches'], - ['borough' => 'Manhattan'], - ['restaurant_id' => '1234'], + ['name' => 'Mongo\'s Deli'], + ['cuisine' => 'Sandwiches'], + ['borough' => 'Manhattan'], + ['restaurant_id' => '1234'], ], ], [ 'updateOne' => [ - ['name' => 'Mongo\'s Deli'], + ['name' => 'Mongo\'s Deli'], ['$set' => ['cuisine' => 'Sandwiches and Salads']], ], ], @@ -36,14 +34,14 @@ // end-run-bulk // start-bulk-options -$result = $collection->bulkWrite( +$result = $restaurantCollection->bulkWrite( [ [ 'insertOne' => [ - ['name' => 'Mongo\'s Pizza'], - ['cuisine' => 'Italian'], - ['borough' => 'Queens'], - ['restaurant_id' => '5678'], + ['name' => 'Mongo\'s Pizza'], + ['cuisine' => 'Italian'], + ['borough' => 'Queens'], + ['restaurant_id' => '5678'], ], ], [ @@ -55,3 +53,95 @@ ['ordered' => false] ); // end-bulk-options + +// start-bulk-client-insert-one +$restaurantCollection = $client->sample_restaurants->restaurants; +$movieCollection = $client->sample_mflix->movies; + +$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection); +$bulkWrite->insertOne(['name' => 'Mongo Deli', 'cuisine' => 'Sandwiches']); + +$bulkWrite = MongoDB\ClientBulkWrite::withCollection($movieCollection); +$bulkWrite->insertOne(['title' => 'The Green Ray', 'year' => 1986]); +// end-bulk-client-insert-one + +// start-bulk-client-update-one +$restaurantCollection = $client->sample_restaurants->restaurants; +$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection); + +$bulkWrite->updateOne( + ['name' => 'Dandelion Bakery'], + ['$set' => ['grade' => 'B+']], + ['upsert' => true], +); +// end-bulk-client-update-one + +// start-bulk-client-update-many +$restaurantCollection = $client->sample_restaurants->restaurants; +$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection); + +$bulkWrite->updateMany( + ['name' => 'Starbucks'], + ['$set' => ['cuisine' => 'Coffee (Chain)']], +); +// end-bulk-client-update-many + +// start-bulk-client-replace-one +$restaurantCollection = $client->sample_restaurants->restaurants; +$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection); + +$bulkWrite->replaceOne( + ['name' => 'Dandelion Bakery'], + ['name' => 'Flower Patisserie', 'cuisine' => 'Bakery & Cafe'], +); +// end-bulk-client-replace-one + +// start-bulk-client-delete-one +$restaurantCollection = $client->sample_restaurants->restaurants; +$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection); + +$bulkWrite->deleteOne( + ['borough' => 'Queens'], +); +// end-bulk-client-delete-one + +// start-bulk-client-delete-many +$restaurantCollection = $client->sample_restaurants->restaurants; +$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection); + +$bulkWrite->deleteMany( + ['name' => ['$regex' => 'p{2,}']], +); +// end-bulk-client-delete-many + +// start-bulk-client +$restaurantCollection = $client->sample_restaurants->restaurants; +$movieCollection = $client->sample_mflix->movies; + +$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection); +$bulkWrite->insertOne(['name' => 'Mongo Deli', 'cuisine' => 'Sandwiches']); +$bulkWrite->updateOne( + ['name' => 'Dandelion Bakery'], + ['$set' => ['grade' => 'B+']], + ['upsert' => true], +); + +$bulkWrite = MongoDB\ClientBulkWrite::withCollection($movieCollection); +$bulkWrite->insertOne(['title' => 'The Green Ray', 'year' => 1986]); +$bulkWrite->deleteMany( + ['title' => ['$regex' => 'd{2,}']], +); +$bulkWrite->replaceOne( + ['runtime' => ['$gte' => 200]], + ['title' => 'Seven Samurai', 'runtime' => 203], +); + +$result = $client->bulkWrite($bulkWrite); +echo 'Inserted documents: ', $result->getInsertedCount(), PHP_EOL; +echo 'Modified documents: ', $result->getModifiedCount(), PHP_EOL; +echo 'Deleted documents: ', $result->getDeletedCount(), PHP_EOL; +// end-bulk-client + +// start-bulk-client-options +$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($collection, ['ordered' => false]); +// end-bulk-client-options diff --git a/source/reference.txt b/source/reference.txt index d987e7c8..b66b65c7 100644 --- a/source/reference.txt +++ b/source/reference.txt @@ -11,6 +11,7 @@ API Documentation BSON MongoDB\Client + MongoDB\ClientBulkWrite MongoDB\Database MongoDB\Collection MongoDB\GridFS\Bucket diff --git a/source/reference/class/MongoDBBulkWriteCommandResult.txt b/source/reference/class/MongoDBBulkWriteCommandResult.txt new file mode 100644 index 00000000..4fac3c38 --- /dev/null +++ b/source/reference/class/MongoDBBulkWriteCommandResult.txt @@ -0,0 +1,61 @@ +===================================== +MongoDB\\BulkWriteCommandResult Class +===================================== + +Definition +---------- + +.. phpclass:: MongoDB\BulkWriteCommandResult + + This class contains information about an executed client bulk write operation. It + is returned from :phpmethod:`MongoDB\Client::bulkWrite()`. + +Methods +------- + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Method + - Description + + * - ``getInsertedCount()`` + - | Returns the number of documents inserted, if any. + + * - ``getMatchedCount()`` + - | Returns the number of documents matched during update and replace + operations, if applicable. + + * - ``getModifiedCount()`` + - | Returns the number of documents modified, if any. + + * - ``getUpsertedCount()`` + - | Returns the number of documents upserted, if any. + + * - ``getDeletedCount()`` + - | Returns the number of documents deleted, if any. + + * - ``getInsertResults()`` + - | Returns a map of results of each successful insert operation. Each + operation is represented by an integer key, which contains a + document with information corresponding to the operation such + as the inserted ``_id`` value. + + * - ``getUpdateResults()`` + - | Returns a map of results of each successful update operation. Each + operation is represented by an integer key, which contains a + document with information corresponding to the operation. + + * - ``getDeleteResults()`` + - | Returns a map of results of each successful delete operation. + Each operation is represented by an integer key, which contains + a document with information corresponding to the operation. + + * - ``isAcknowledged()`` + - | Returns a boolean indicating whether the bulk operation was acknowledged. + +See Also +-------- + +- :ref:`php-bulk-write` diff --git a/source/reference/class/MongoDBClient.txt b/source/reference/class/MongoDBClient.txt index 36b3cea6..0dc61e25 100644 --- a/source/reference/class/MongoDBClient.txt +++ b/source/reference/class/MongoDBClient.txt @@ -32,6 +32,7 @@ Methods __construct() __get() addSubscriber() + bulkWrite() createClientEncryption() dropDatabase() getCollection() @@ -52,6 +53,7 @@ Methods - :phpmethod:`MongoDB\Client::__construct()` - :phpmethod:`MongoDB\Client::__get()` - :phpmethod:`MongoDB\Client::addSubscriber()` +- :phpmethod:`MongoDB\Client::bulkWrite()` - :phpmethod:`MongoDB\Client::createClientEncryption()` - :phpmethod:`MongoDB\Client::dropDatabase()` - :phpmethod:`MongoDB\Client::getCollection()` @@ -67,4 +69,4 @@ Methods - :phpmethod:`MongoDB\Client::selectCollection()` - :phpmethod:`MongoDB\Client::selectDatabase()` - :phpmethod:`MongoDB\Client::startSession()` -- :phpmethod:`MongoDB\Client::watch()` \ No newline at end of file +- :phpmethod:`MongoDB\Client::watch()` diff --git a/source/reference/class/MongoDBClientBulkWrite.txt b/source/reference/class/MongoDBClientBulkWrite.txt new file mode 100644 index 00000000..9d7f9f7c --- /dev/null +++ b/source/reference/class/MongoDBClientBulkWrite.txt @@ -0,0 +1,45 @@ +============================== +MongoDB\\ClientBulkWrite Class +============================== + +.. versionadded:: 2.1 + +Definition +---------- + +.. phpclass:: MongoDB\ClientBulkWrite + + This class allows you to assemble a bulk write command to pass to + :phpmethod:`MongoDB\Client::bulkWrite()`. + + This class allows you to specify write operations across multiple + namespaces in the same cluster. + +Methods +------- + +.. toctree:: + :titlesonly: + + createWithCollection() + deleteMany() + deleteOne() + insertOne() + replaceOne() + updateMany() + updateOne() + withCollection() + +- :phpmethod:`MongoDB\ClientBulkWrite::createWithCollection()` +- :phpmethod:`MongoDB\ClientBulkWrite::deleteMany()` +- :phpmethod:`MongoDB\ClientBulkWrite::deleteOne()` +- :phpmethod:`MongoDB\ClientBulkWrite::insertOne()` +- :phpmethod:`MongoDB\ClientBulkWrite::replaceOne()` +- :phpmethod:`MongoDB\ClientBulkWrite::updateMany()` +- :phpmethod:`MongoDB\ClientBulkWrite::updateOne()` +- :phpmethod:`MongoDB\ClientBulkWrite::withCollection()` + +See Also +-------- + +- :ref:`php-bulk-write` diff --git a/source/reference/method/MongoDBClient-bulkWrite.txt b/source/reference/method/MongoDBClient-bulkWrite.txt new file mode 100644 index 00000000..a002eb1e --- /dev/null +++ b/source/reference/method/MongoDBClient-bulkWrite.txt @@ -0,0 +1,100 @@ +============================ +MongoDB\\Client::bulkWrite() +============================ + +.. meta:: + :description: Perform write operations across multiple namespaces by using the MongoDB PHP Library. + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. versionadded:: 2.1 + +Definition +---------- + +.. phpmethod:: MongoDB\Client::bulkWrite() + + Executes multiple write operations across multiple namespaces. + + .. code-block:: php + + function bulkWrite( + BulkWriteCommand|ClientBulkWrite $bulk, + array $options = [] + ): MongoDB\BulkWriteCommandResult + +Parameters +---------- + +``$bulk`` : :phpclass:`MongoDB\ClientBulkWrite` or ``BulkWriteCommand`` + (reserve for use with the {+extension-short+} only) + + Represents the assembled bulk write command or builder. + :phpmethod:`MongoDB\Client::bulkWrite()` supports + :phpmethod:`MongoDB\Collection::deleteMany()`, + :phpmethod:`MongoDB\Collection::deleteOne()`, + :phpmethod:`MongoDB\Collection::insertOne()`, + :phpmethod:`MongoDB\Collection::replaceOne()`, + :phpmethod:`MongoDB\Collection::updateMany()`, and + :phpmethod:`MongoDB\Collection::updateOne()` operations. + + The ``writeConcern`` option is specified as a top-level option to + :phpmethod:`MongoDB\Client::bulkWrite()` instead of each individual + operation. + +``$options`` : array + An array specifying the desired options. + + .. list-table:: + :header-rows: 1 + :widths: 20 20 80 + + * - Name + - Type + - Description + + * - session + - :php:`MongoDB\Driver\Session ` + - .. include:: /includes/extracts/common-option-session.rst + + * - writeConcern + - :php:`MongoDB\Driver\WriteConcern ` + - .. include:: /includes/extracts/collection-option-writeConcern.rst + + .. include:: /includes/extracts/common-option-writeConcern-transaction.rst + +Return Values +------------- + +A :phpclass:`MongoDB\BulkWriteCommandResult` object. + +Errors/Exceptions +----------------- + +.. include:: /includes/extracts/error-unsupportedexception.rst +.. include:: /includes/extracts/error-invalidargumentexception.rst +.. include:: /includes/extracts/error-driver-runtimeexception.rst +.. include:: /includes/extracts/error-driver-client-bulkwriteexception.rst + +Behavior +-------- + +.. include:: /includes/extracts/bulkwriteexception-client-result.rst +.. include:: /includes/extracts/bulkwriteexception-ordered.rst + +See Also +-------- + +- :ref:`php-bulk-write` +- :ref:`php-write` +- :phpmethod:`MongoDB\Collection::deleteMany()` +- :phpmethod:`MongoDB\Collection::deleteOne()` +- :phpmethod:`MongoDB\Collection::insertMany()` +- :phpmethod:`MongoDB\Collection::insertOne()` +- :phpmethod:`MongoDB\Collection::replaceOne()` +- :phpmethod:`MongoDB\Collection::updateMany()` +- :phpmethod:`MongoDB\Collection::updateOne()` diff --git a/source/reference/method/MongoDBClientBulkWrite-createWithCollection.txt b/source/reference/method/MongoDBClientBulkWrite-createWithCollection.txt new file mode 100644 index 00000000..d021a1ca --- /dev/null +++ b/source/reference/method/MongoDBClientBulkWrite-createWithCollection.txt @@ -0,0 +1,85 @@ +================================================ +MongoDB\\ClientBulkWrite::createWithCollection() +================================================ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. versionadded:: 2.1 + +Definition +---------- + +.. phpmethod:: MongoDB\ClientBulkWrite::createWithCollection() + + Creates an instance of :phpclass:`MongoDB\ClientBulkWrite` from the provided + :phpclass:`MongoDB\Collection` instance. + + .. code-block:: php + + function createWithCollection( + Collection $collection, + array $options = [] + ): self + +Parameters +---------- + +``$collection`` : :phpclass:`MongoDB\Collection` + The ``Collection`` instance to set as the target for bulk write + operations. + +``$options`` : array + An array specifying the desired options. + + .. list-table:: + :header-rows: 1 + :widths: 20 20 80 + + * - Name + - Type + - Description + + * - bypassDocumentValidation + - boolean + - If ``true``, allows the write operation to circumvent document level + validation. Defaults to ``false``. + + * - comment + - mixed + - .. include:: /includes/extracts/common-option-comment.rst + + .. include:: /includes/extracts/option-requires-4.4.rst + + * - let + - array|object + - .. include:: /includes/extracts/common-option-let.rst + + * - ordered + - boolean + - If ``true``: when a single write fails, the operation stops without + performing the remaining writes and throws an exception. + + If ``false``: when a single write fails, the operation continues + with the remaining writes, if any, and throws an exception. + + The default is ``true``. + + * - verboseResults + - boolean + - Specifies whether to return verbose results. The default is ``false``. + +Errors/Exceptions +----------------- + +.. include:: /includes/extracts/error-unsupportedexception.rst +.. include:: /includes/extracts/error-invalidargumentexception.rst +.. include:: /includes/extracts/error-driver-runtimeexception.rst + +See Also +-------- + +- :ref:`php-bulk-write` diff --git a/source/reference/method/MongoDBClientBulkWrite-deleteMany.txt b/source/reference/method/MongoDBClientBulkWrite-deleteMany.txt new file mode 100644 index 00000000..6af3330a --- /dev/null +++ b/source/reference/method/MongoDBClientBulkWrite-deleteMany.txt @@ -0,0 +1,73 @@ +====================================== +MongoDB\\ClientBulkWrite::deleteMany() +====================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. versionadded:: 2.1 + +Definition +---------- + +.. phpmethod:: MongoDB\ClientBulkWrite::deleteMany() + + Specifies a delete operation in the bulk write command for all + matching documents. This method returns the + :phpclass:`MongoDB\ClientBulkWrite` instance on which its called. + + .. code-block:: php + + function deleteMany( + array|object $filter, + array $options = [] + ): self + +Parameters +---------- + +``$filter`` : array|object + The filter criteria that specifies the documents to delete. + +``$options`` : array + An array specifying the desired options. + + .. list-table:: + :header-rows: 1 + :widths: 20 20 80 + + * - Name + - Type + - Description + + * - collation + - array|object + - .. include:: /includes/extracts/collection-option-collation.rst + + * - hint + - string|array|object + - .. include:: /includes/extracts/common-option-hint.rst + + .. include:: /includes/extracts/option-requires-4.4.rst + +Errors/Exceptions +----------------- + +.. include:: /includes/extracts/error-unsupportedexception.rst +.. include:: /includes/extracts/error-invalidargumentexception.rst +.. include:: /includes/extracts/error-driver-client-bulkwriteexception.rst +.. include:: /includes/extracts/error-driver-runtimeexception.rst + +Behavior +-------- + +.. include:: /includes/extracts/note-bson-comparison.rst +.. include:: /includes/extracts/bulkwriteexception-client-result.rst + +See Also +-------- + +- :ref:`php-bulk-write` diff --git a/source/reference/method/MongoDBClientBulkWrite-deleteOne.txt b/source/reference/method/MongoDBClientBulkWrite-deleteOne.txt new file mode 100644 index 00000000..d0e10ffa --- /dev/null +++ b/source/reference/method/MongoDBClientBulkWrite-deleteOne.txt @@ -0,0 +1,73 @@ +===================================== +MongoDB\\ClientBulkWrite::deleteOne() +===================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. versionadded:: 2.1 + +Definition +---------- + +.. phpmethod:: MongoDB\ClientBulkWrite::deleteOne() + + Specifies a delete operation in the bulk write command for the first + matching document. This method returns the + :phpclass:`MongoDB\ClientBulkWrite` instance on which its called. + + .. code-block:: php + + function deleteMany( + array|object $filter, + array $options = [] + ): self + +Parameters +---------- + +``$filter`` : array|object + The filter criteria that specifies the document to delete. + +``$options`` : array + An array specifying the desired options. + + .. list-table:: + :header-rows: 1 + :widths: 20 20 80 + + * - Name + - Type + - Description + + * - collation + - array|object + - .. include:: /includes/extracts/collection-option-collation.rst + + * - hint + - string|array|object + - .. include:: /includes/extracts/common-option-hint.rst + + .. include:: /includes/extracts/option-requires-4.4.rst + +Errors/Exceptions +----------------- + +.. include:: /includes/extracts/error-unsupportedexception.rst +.. include:: /includes/extracts/error-invalidargumentexception.rst +.. include:: /includes/extracts/error-driver-client-bulkwriteexception.rst +.. include:: /includes/extracts/error-driver-runtimeexception.rst + +Behavior +-------- + +.. include:: /includes/extracts/note-bson-comparison.rst +.. include:: /includes/extracts/bulkwriteexception-client-result.rst + +See Also +-------- + +- :ref:`php-bulk-write` diff --git a/source/reference/method/MongoDBClientBulkWrite-insertOne.txt b/source/reference/method/MongoDBClientBulkWrite-insertOne.txt new file mode 100644 index 00000000..c2b6ac71 --- /dev/null +++ b/source/reference/method/MongoDBClientBulkWrite-insertOne.txt @@ -0,0 +1,53 @@ +===================================== +MongoDB\\ClientBulkWrite::insertOne() +===================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. versionadded:: 2.1 + +Definition +---------- + +.. phpmethod:: MongoDB\ClientBulkWrite::insertOne() + + Specifies an insert operation in the bulk write command. This method + returns the :phpclass:`MongoDB\ClientBulkWrite` instance on which its called. + + .. code-block:: php + + function insertOne( + array|object $document, + mixed &$id = null + ): self + +Parameters +---------- + +``$document`` : array|object + The document to insert into the collection. + +``$id`` : mixed + Captures the document's ``_id`` field value to store in an optional + output variable. + +Errors/Exceptions +----------------- + +.. include:: /includes/extracts/error-invalidargumentexception.rst +.. include:: /includes/extracts/error-driver-client-bulkwriteexception.rst +.. include:: /includes/extracts/error-driver-runtimeexception.rst + +Behavior +-------- + +.. include:: /includes/extracts/bulkwriteexception-client-result.rst + +See Also +-------- + +- :ref:`php-bulk-write` diff --git a/source/reference/method/MongoDBClientBulkWrite-replaceOne.txt b/source/reference/method/MongoDBClientBulkWrite-replaceOne.txt new file mode 100644 index 00000000..87266882 --- /dev/null +++ b/source/reference/method/MongoDBClientBulkWrite-replaceOne.txt @@ -0,0 +1,89 @@ +====================================== +MongoDB\\ClientBulkWrite::replaceOne() +====================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. versionadded:: 2.1 + +Definition +---------- + +.. phpmethod:: MongoDB\ClientBulkWrite::replaceOne() + + Specifies a replace operation in the bulk write command for the first + matching document. This method returns the + :phpclass:`MongoDB\ClientBulkWrite` instance on which its called. + + .. code-block:: php + + function replaceOne( + array|object $filter, + array|object $replacement, + array $options = [] + ): self + +Parameters +---------- + +``$filter`` : array|object + The filter criteria that specifies the documents to replace. + +``$replacement`` : array|object + The replacement document. + +``$options`` : array + An array specifying the desired options. + + .. list-table:: + :header-rows: 1 + :widths: 20 20 80 + + * - Name + - Type + - Description + + * - collation + - array|object + - .. include:: /includes/extracts/collection-option-collation.rst + + * - hint + - string|array|object + - .. include:: /includes/extracts/common-option-hint.rst + + .. include:: /includes/extracts/option-requires-4.2.rst + + * - sort + - array|object + - The sort specification for the ordering of the matched + documents. Set this option to apply an order to matched + documents before the server performs the replace operation. + + * - upsert + - boolean + - If set to ``true``, creates a new document when no document matches the + query criteria. The default value is ``false``, which does not insert a + new document when no match is found. + +Errors/Exceptions +----------------- + +.. include:: /includes/extracts/error-unsupportedexception.rst +.. include:: /includes/extracts/error-invalidargumentexception.rst +.. include:: /includes/extracts/error-driver-client-bulkwriteexception.rst +.. include:: /includes/extracts/error-driver-runtimeexception.rst + +Behavior +-------- + +.. include:: /includes/extracts/note-bson-comparison.rst +.. include:: /includes/extracts/bulkwriteexception-client-result.rst + +See Also +-------- + +- :ref:`php-bulk-write` diff --git a/source/reference/method/MongoDBClientBulkWrite-updateMany.txt b/source/reference/method/MongoDBClientBulkWrite-updateMany.txt new file mode 100644 index 00000000..b417e27b --- /dev/null +++ b/source/reference/method/MongoDBClientBulkWrite-updateMany.txt @@ -0,0 +1,96 @@ +====================================== +MongoDB\\ClientBulkWrite::updateMany() +====================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. versionadded:: 2.1 + +Definition +---------- + +.. phpmethod:: MongoDB\ClientBulkWrite::updateMany() + + Specifies an update operation in the bulk write command for all + matching documents. This method returns the + :phpclass:`MongoDB\ClientBulkWrite` instance on which its called. + + .. code-block:: php + + function updateMany( + array|object $filter, + array|object $update, + array $options = [] + ): self + +Parameters +---------- + +``$filter`` : array|object + The filter criteria that specifies the documents to update. + +``$update`` : array|object + Specifies the field and value combinations to update and any relevant update + operators. ``$update`` uses MongoDB's :manual:`update operators `. + Starting with MongoDB 4.2, you can pass an :manual:`aggregation pipeline + ` + as this parameter. + +``$options`` : array + An array specifying the desired options. + + .. list-table:: + :header-rows: 1 + :widths: 20 20 80 + + * - Name + - Type + - Description + + * - Name + - Type + - Description + + * - arrayFilters + - array + - An array of filter documents that determines which array elements to + modify for an update operation on an array field. + + * - collation + - array|object + - .. include:: /includes/extracts/collection-option-collation.rst + + * - hint + - string|array|object + - .. include:: /includes/extracts/common-option-hint.rst + + .. include:: /includes/extracts/option-requires-4.2.rst + + * - upsert + - boolean + - If set to ``true``, creates a new document when no document matches the + query criteria. The default value is ``false``, which does not insert a + new document when no match is found. + +Errors/Exceptions +----------------- + +.. include:: /includes/extracts/error-unsupportedexception.rst +.. include:: /includes/extracts/error-invalidargumentexception.rst +.. include:: /includes/extracts/error-driver-client-bulkwriteexception.rst +.. include:: /includes/extracts/error-driver-runtimeexception.rst + +Behavior +-------- + +.. include:: /includes/extracts/note-bson-comparison.rst +.. include:: /includes/extracts/bulkwriteexception-client-result.rst + +See Also +-------- + +- :ref:`php-bulk-write` diff --git a/source/reference/method/MongoDBClientBulkWrite-updateOne.txt b/source/reference/method/MongoDBClientBulkWrite-updateOne.txt new file mode 100644 index 00000000..b9b7710c --- /dev/null +++ b/source/reference/method/MongoDBClientBulkWrite-updateOne.txt @@ -0,0 +1,98 @@ +===================================== +MongoDB\\ClientBulkWrite::updateOne() +===================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. versionadded:: 2.1 + +Definition +---------- + +.. phpmethod:: MongoDB\ClientBulkWrite::updateOne() + + Specifies an update operation in the bulk write command for the first + matching document. This method returns the + :phpclass:`MongoDB\ClientBulkWrite` instance on which its called. + + .. code-block:: php + + function updateOne( + array|object $filter, + array|object $update, + array $options = [] + ): self + +Parameters +---------- + +``$filter`` : array|object + The filter criteria that specifies the documents to update. + +``$update`` : array|object + Specifies the field and value combinations to update and any relevant update + operators. ``$update`` uses MongoDB's :manual:`update operators + `. Starting with MongoDB 4.2, an `aggregation + pipeline `_ + can be passed as this parameter. + +``$options`` : array + An array specifying the desired options. + + .. list-table:: + :header-rows: 1 + :widths: 20 20 80 + + * - Name + - Type + - Description + + * - arrayFilters + - array + - An array of filter documents that determines which array elements to modify + for an update operation on an array field. + + * - collation + - array|object + - .. include:: /includes/extracts/collection-option-collation.rst + + * - hint + - string|array|object + - .. include:: /includes/extracts/common-option-hint.rst + + .. include:: /includes/extracts/option-requires-4.2.rst + + * - sort + - array|object + - The sort specification for the ordering of the matched + documents. Set this option to apply an order to matched + documents before the server performs the update operation. + + * - upsert + - boolean + - If set to ``true``, creates a new document when no document matches the + query criteria. The default value is ``false``, which does not insert a + new document when no match is found. + +Errors/Exceptions +----------------- + +.. include:: /includes/extracts/error-unsupportedexception.rst +.. include:: /includes/extracts/error-invalidargumentexception.rst +.. include:: /includes/extracts/error-driver-client-bulkwriteexception.rst +.. include:: /includes/extracts/error-driver-runtimeexception.rst + +Behavior +-------- + +.. include:: /includes/extracts/note-bson-comparison.rst +.. include:: /includes/extracts/bulkwriteexception-client-result.rst + +See Also +-------- + +- :ref:`php-bulk-write` diff --git a/source/reference/method/MongoDBClientBulkWrite-withCollection.txt b/source/reference/method/MongoDBClientBulkWrite-withCollection.txt new file mode 100644 index 00000000..071066e4 --- /dev/null +++ b/source/reference/method/MongoDBClientBulkWrite-withCollection.txt @@ -0,0 +1,50 @@ +========================================== +MongoDB\\ClientBulkWrite::withCollection() +========================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. versionadded:: 2.1 + +Definition +---------- + +.. phpmethod:: MongoDB\ClientBulkWrite::withCollection() + + Creates an instance of :phpclass:`MongoDB\ClientBulkWrite` from the provided + :phpclass:`MongoDB\Collection` instance. This method allows you to + add subsequent write operations on a different collection than that + which the ``MongoDB\ClientBulkWrite`` was created with. + + .. code-block:: php + + function withCollection( + Collection $collection, + ): self + + + You cannot mix ``Collection`` instances associated with different + ``Manager`` objects. + +Parameters +---------- + +``$collection`` : :phpclass:`MongoDB\Collection` + The ``Collection`` instance to set as the target for bulk write + operations. + +Errors/Exceptions +----------------- + +.. include:: /includes/extracts/error-unsupportedexception.rst +.. include:: /includes/extracts/error-invalidargumentexception.rst +.. include:: /includes/extracts/error-driver-runtimeexception.rst + +See Also +-------- + +- :ref:`php-bulk-write` diff --git a/source/reference/result-classes.txt b/source/reference/result-classes.txt index db2a1b66..a6aa9455 100644 --- a/source/reference/result-classes.txt +++ b/source/reference/result-classes.txt @@ -5,6 +5,7 @@ Result Classes .. toctree:: :titlesonly: + BulkWriteCommandResult BulkWriteResult DeleteResult InsertManyResult diff --git a/source/write/bulk-write.txt b/source/write/bulk-write.txt index bf9abcec..70c39bd2 100644 --- a/source/write/bulk-write.txt +++ b/source/write/bulk-write.txt @@ -15,40 +15,47 @@ Bulk Write Operations :values: reference .. meta:: - :keywords: insert, update, replace, code example + :keywords: insert, update, replace, code example, multiple changes Overview -------- -In this guide, you can learn how to perform multiple write operations -in a single database call by using **bulk write operations**. +In this guide, you can learn how to perform multiple write operations in +a single database call by using **bulk write operations**. -Consider a scenario in which you want to insert a document into a collection, +Consider a scenario in which you want to insert a document, update multiple other documents, then delete a document. If you use -individual methods, each operation requires its own database call. Instead, -you can use a bulk operation to reduce the number of calls to the database. +individual methods, each operation requires its own database call. -Sample Data -~~~~~~~~~~~ +By using a bulk write operation, you can perform multiple write operations in +fewer database calls. You can perform bulk write operations at the following levels: -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: +- :ref:`Collection `: You can use the + ``MongoDB\Collection::bulkWrite()`` method to perform bulk write + operations on a single collection. This method makes a database call + for each type of write operation. For example, the method can perform + multiple update operations in one call, but makes two separate calls to + the database for an insert operation and a replace operation. -.. literalinclude:: /includes/write/bulk-write.php - :language: php - :dedent: - :start-after: start-db-coll - :end-before: end-db-coll +- :ref:`Client `: If your application connects to + {+mdb-server+} version 8.0 or later, you can use the + ``MongoDB\Client::bulkWrite()`` method to perform bulk write + operations on multiple collections and databases in the same cluster. + This method performs all write operations in one database call. + +Sample Data +~~~~~~~~~~~ -To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the -:atlas:`Get Started with Atlas ` guide. +The examples in this guide use the ``sample_restaurants.restaurants`` +and ``sample_mflix.movies`` collections 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. -.. _php-bulk-operations: +.. _php-coll-bulk-write: -Bulk Operations ---------------- +Collection Bulk Write +--------------------- To run a bulk write operation, pass an array of write operations to the ``MongoDB\Collection::bulkWrite()`` method. Use the following syntax to @@ -67,13 +74,13 @@ specify the write operations: .. tip:: - For more information about delete, insert, replace, and update - operations, see the :ref:`Write operation guides `. + To learn more about delete, insert, replace, and update + operations, see the guides in the :ref:`php-write` section. When you call the ``bulkWrite()`` method, the library automatically runs the -write operations in the order they're specified in the array. To learn how to +write operations in the order you specify in the array. To learn how to instruct ``bulkWrite()`` to run the write operations in an arbitrary order, -see the :ref:`php-bulk-modify` section. +see the :ref:`php-bulk-collection-modify` section. Example ~~~~~~~ @@ -96,10 +103,16 @@ collection: :language: php :dedent: -.. _php-bulk-modify: +.. note:: + + When the library runs a bulk operation, it uses the write concern of the + target collection. The driver reports all write concern errors after + attempting all operations, regardless of execution order. + +.. _php-bulk-collection-modify: -Modify Bulk Write Behavior --------------------------- +Customize Bulk Write Operation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can modify the behavior of the ``MongoDB\Collection::bulkWrite()`` method by passing an array that specifies option values as a parameter. The following table @@ -170,19 +183,19 @@ If it runs the delete operation first, no documents are deleted. Unordered bulk operations do not guarantee order of execution. The order can differ from the way you list them to optimize the runtime. -.. _php-bulk-return-value: +.. _php-bulk-collection-return-value: Return Value ------------- +~~~~~~~~~~~~ The ``MongoDB\Collection::bulkWrite()`` method returns a ``MongoDB\BulkWriteResult`` -object. This class contains the following member functions: +object. This class contains the following methods: .. list-table:: :widths: 30 70 :header-rows: 1 - * - Function + * - Method - Description * - ``getDeletedCount()`` @@ -210,6 +223,295 @@ object. This class contains the following member functions: * - ``isAcknowledged()`` - | Returns a boolean indicating whether the bulk operation was acknowledged. +.. _php-client-bulk-write: + +Client Bulk Write +----------------- + +When using {+library-short+} v2.1 and connecting to a deployment +running {+mdb-server+} 8.0 or later, you can use the +``MongoDB\Client::bulkWrite()`` method to write to multiple databases +and collections in the same cluster. This method performs all write +operations in a single call. To learn more about this feature, see the +:manual:`Mongo.bulkWrite() ` +reference in the {+mdb-server+} manual. + +First, instantiate a ``MongoDB\ClientBulkWrite`` instance that +specifies the write operations to perform. The following code +demonstrates how to create a ``ClientBulkWrite`` instance from a +``MongoDB\Collection`` instance by using the ``createWithCollection()`` +method: + +.. code-block:: php + :emphasize-lines: 2 + + $restaurantCollection = $client->sample_restaurants->restaurants; + $bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection); + +Then, call one or more of the following write methods on the +``ClientBulkWrite`` instance to construct the bulk write operation: + +- ``deleteOne()`` +- ``deleteMany()`` +- ``insertOne()`` +- ``replaceOne()`` +- ``updateOne()`` +- ``updateMany()`` + +To select a different namespace for subsequent write operations, call +the ``withCollection()`` method on the ``ClientBulkWrite`` instance: + +.. code-block:: php + :emphasize-lines: 2 + + $movieCollection = $client->sample_mflix->movies; + $bulkWrite = MongoDB\ClientBulkWrite::withCollection($movieCollection); + +The following sections show how to create and use the +``ClientBulkWrite`` class to specify write operations +in a bulk write. The :ref:`php-client-bulkwrite-method` section +demonstrates how to pass the ``ClientBulkWrite`` object to the +``bulkWrite()`` method to perform the bulk operation. + +Insert Operations +~~~~~~~~~~~~~~~~~ + +To specify an insert operation, create an instance of the +``ClientBulkWrite`` class, then call the ``insertOne()`` method. + +The following example specifies insertion of documents into the +``sample_restaurants.restaurants`` and ``sample_mflix.movies`` +collections: + +.. literalinclude:: /includes/write/bulk-write.php + :start-after: start-bulk-client-insert-one + :end-before: end-bulk-client-insert-one + :language: php + :copyable: + :dedent: + +Update Operations +~~~~~~~~~~~~~~~~~ + +To specify an update operation on the first matching document, create an +instance of the ``ClientBulkWrite`` class, then call the ``updateOne()`` +method. + +The following example specifies an update to a document in the +``sample_restaurants.restaurants`` collection: + +.. literalinclude:: /includes/write/bulk-write.php + :start-after: start-bulk-client-update-one + :end-before: end-bulk-client-update-one + :language: php + :copyable: + :dedent: + +To update multiple documents, call the ``updateMany()`` method. The specified +operation updates *all documents* that match the query filter. + +The following example specifies an update to all matching documents in the +``sample_restaurants.restaurants`` collection: + +.. literalinclude:: /includes/write/bulk-write.php + :start-after: start-bulk-client-update-many + :end-before: end-bulk-client-update-many + :language: php + :copyable: + :dedent: + +Replace Operations +~~~~~~~~~~~~~~~~~~ + +To specify an replace operation on the first matching document, create an +instance of the ``ClientBulkWrite`` class, then call the ``replaceOne()`` +method. + +The following example specifies a replace operation on a document in the +``sample_restaurants.restaurants`` collection: + +.. literalinclude:: /includes/write/bulk-write.php + :start-after: start-bulk-client-replace-one + :end-before: end-bulk-client-replace-one + :language: php + :copyable: + :dedent: + +Delete Operations +~~~~~~~~~~~~~~~~~ + +To specify an delete operation on the first matching document, create an +instance of the ``ClientBulkWrite`` class, then call the ``deleteOne()`` +method. + +The following example specifies deletion of a document in the +``sample_restaurants.restaurants`` collection: + +.. literalinclude:: /includes/write/bulk-write.php + :start-after: start-bulk-client-delete-one + :end-before: end-bulk-client-delete-one + :language: php + :copyable: + :dedent: + +To delete multiple documents, call the ``deleteMany()`` method. The specified +operation deletes *all documents* that match the query filter. + +The following example specifies deletion of all matching documents in the +``sample_restaurants.restaurants`` collection: + +.. literalinclude:: /includes/write/bulk-write.php + :start-after: start-bulk-client-delete-many + :end-before: end-bulk-client-delete-many + :language: php + :copyable: + :dedent: + +.. _php-client-bulkwrite-method: + +Perform the Bulk Operation +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +After you construct the ``ClientBulkWrite`` instance to specify your +write operations, pass it to the ``MongoDB\Client::bulkWrite()`` method. +By default, these methods run the operations in the order you defined +when constructing ``ClientBulkWrite``. + +The following code demonstrates how to use the ``bulkWrite()`` method +to perform a bulk write operation on multiple namespaces: + +.. io-code-block:: + :copyable: + + .. input:: /includes/write/bulk-write.php + :start-after: start-bulk-client + :end-before: end-bulk-client + :language: php + :dedent: + + .. output:: + :visible: false + + Inserted documents: 2 + Modified documents: 2 + Deleted documents: 200 + +.. _php-client-bulk-write-options: + +Customize Bulk Write +~~~~~~~~~~~~~~~~~~~~ + +You can modify the behavior of the client bulk write operation by +passing an array to the ``ClientBulkWrite`` constructor that specifies +option values as a parameter. The following table describes the options +you can set in the array: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Option + - Description + + * - ``bypassDocumentValidation`` + - | Specifies whether the operation bypasses document validation. This lets you + modify documents that don't meet the schema validation requirements, if any + exist. For more information about schema validation, see :manual:`Schema + Validation ` in the {+mdb-server+} + manual. + | Defaults to ``false``. + + * - ``comment`` + - | Attaches a comment to the operation. For more information, see the :manual:`insert command + fields ` guide 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. + + * - ``ordered`` + - | If set to ``true``: when a single write fails, the operation stops without + performing the remaining writes and throws an exception. + | If set to ``false``: when a single write fails, the operation continues to + attempt the remaining write operations, if any, then throws an exception. + | Defaults to ``true``. + + * - ``verboseResults`` + - | Specifies whether to return verbose results. + | Defaults to ``false``. + +The following example creates a ``ClientBulkWrite`` instance and sets +the ``ordered`` option to ``false``: + +.. literalinclude:: /includes/write/bulk-write.php + :start-after: start-bulk-client-options + :end-before: end-bulk-client-options + :language: php + :dedent: + +If the library runs the insert operation first, one document is deleted. +If it runs the delete operation first, no documents are deleted. + +.. note:: + + Unordered bulk operations do not guarantee order of execution. The order can + differ from the way you list them to optimize the runtime. + +You can also pass options when calling the ``bulkWrite()`` method to specify +the client session or the write concern to use for the operation. + +Return Value +~~~~~~~~~~~~ + +The ``MongoDB\Client::bulkWrite()`` method returns a ``MongoDB\BulkWriteCommandResult`` +object. This class contains the following methods: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Method + - Description + + * - ``getInsertedCount()`` + - | Returns the number of documents inserted, if any. + + * - ``getMatchedCount()`` + - | Returns the number of documents matched during update and replace + operations, if applicable. + + * - ``getModifiedCount()`` + - | Returns the number of documents modified, if any. + + * - ``getUpsertedCount()`` + - | Returns the number of documents upserted, if any. + + * - ``getDeletedCount()`` + - | Returns the number of documents deleted, if any. + + * - ``getInsertResults()`` + - | Returns a map of results of each successful insert operation. Each + operation is represented by an integer key, which contains a + document with information corresponding to the operation such + as the inserted ``_id`` value. + + * - ``getUpdateResults()`` + - | Returns a map of results of each successful update operation. Each + operation is represented by an integer key, which contains a + document with information corresponding to the operation. + + * - ``getDeleteResults()`` + - | Returns a map of results of each successful delete operation. + Each operation is represented by an integer key, which contains + a document with information corresponding to the operation. + + * - ``isAcknowledged()`` + - | Returns a boolean indicating whether the bulk operation was acknowledged. + Additional Information ---------------------- @@ -226,5 +528,13 @@ API Documentation To learn more about any of the methods or types discussed in this guide, see the following API documentation: -- :phpmethod:`MongoDB\Collection::bulkWrite()` -- :phpclass:`MongoDB\BulkWriteResult` \ No newline at end of file +- Collection Bulk Write + + - :phpmethod:`MongoDB\Collection::bulkWrite()` + - :phpclass:`MongoDB\BulkWriteResult` + +- Client Bulk Write + + - :phpclass:`MongoDB\ClientBulkWrite` + - :phpmethod:`MongoDB\Client::bulkWrite()` + - :phpclass:`MongoDB\BulkWriteCommandResult` diff --git a/source/write/transaction.txt b/source/write/transaction.txt index 5a929cc0..f789683e 100644 --- a/source/write/transaction.txt +++ b/source/write/transaction.txt @@ -163,6 +163,14 @@ completes the following actions: .. sharedinclude:: dbx/transactions-parallelism.rst + .. replacement:: driver-specific-content + + If you're using {+library-short+} v2.1 or later and {+mdb-server+} + v8.0 or later, you can perform write operations on multiple + namespaces within a single transaction by using the + :phpmethod:`MongoDB\Client::bulkWrite()` method. For more + information, see :ref:`php-bulk-write`. + Additional Information ---------------------- From e634bc87f8fefa395eeac5734913f344e27fbba0 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 20 May 2025 09:26:52 -0400 Subject: [PATCH 02/12] first pass fixes --- snooty.toml | 1 + source/includes/extracts-bulkwriteexception.yaml | 2 +- source/includes/extracts-error.yaml | 2 +- source/write/bulk-write.txt | 6 +++--- 4 files changed, 6 insertions(+), 5 deletions(-) diff --git a/snooty.toml b/snooty.toml index 0d6dfcc0..24d9ed5e 100644 --- a/snooty.toml +++ b/snooty.toml @@ -9,6 +9,7 @@ intersphinx = [ toc_landing_pages = [ "/reference/class/MongoDBClient", + "/reference/class/MongoDBClientBulkWrite", "/reference/class/MongoDBCollection", "/reference/class/MongoDBDatabase", "/reference/class/MongoDBGridFSBucket", diff --git a/source/includes/extracts-bulkwriteexception.yaml b/source/includes/extracts-bulkwriteexception.yaml index 3791eec8..75062e6a 100644 --- a/source/includes/extracts-bulkwriteexception.yaml +++ b/source/includes/extracts-bulkwriteexception.yaml @@ -15,7 +15,7 @@ ref: bulkwriteexception-client-result content: | If a :php:`MongoDB\Driver\Exception\BulkWriteCommandException ` is thrown, users should call - :php:`getWriteErrors() ` and + :php:`getWriteErrors() ` and inspect the information in the returned array to determine the nature of the error. For example, a write operation may have been successfully applied to the diff --git a/source/includes/extracts-error.yaml b/source/includes/extracts-error.yaml index 64581a99..cda75f1d 100644 --- a/source/includes/extracts-error.yaml +++ b/source/includes/extracts-error.yaml @@ -11,7 +11,7 @@ content: | :php:`MongoDB\Driver\Exception\BulkWriteCommandException ` for errors related to the write operation. Users should inspect the value returned by :php:`getWriteErrors() - ` to determine the nature of the + ` to determine the nature of the error. --- ref: error-driver-invalidargumentexception diff --git a/source/write/bulk-write.txt b/source/write/bulk-write.txt index 70c39bd2..078e96d2 100644 --- a/source/write/bulk-write.txt +++ b/source/write/bulk-write.txt @@ -58,7 +58,7 @@ Collection Bulk Write --------------------- To run a bulk write operation, pass an array of write operations to the -``MongoDB\Collection::bulkWrite()`` method. Use the following syntax to +:phpmethod:`MongoDB\Collection::bulkWrite()` method. Use the following syntax to specify the write operations: .. code-block:: php @@ -230,10 +230,10 @@ Client Bulk Write When using {+library-short+} v2.1 and connecting to a deployment running {+mdb-server+} 8.0 or later, you can use the -``MongoDB\Client::bulkWrite()`` method to write to multiple databases +:phpmethod:`MongoDB\Client::bulkWrite()` method to write to multiple databases and collections in the same cluster. This method performs all write operations in a single call. To learn more about this feature, see the -:manual:`Mongo.bulkWrite() ` +:manual:`Mongo.bulkWrite() ` reference in the {+mdb-server+} manual. First, instantiate a ``MongoDB\ClientBulkWrite`` instance that From 6a2ab7a3599f34f0837b2f0da67e42a15f75e284 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 20 May 2025 11:29:38 -0400 Subject: [PATCH 03/12] JT PR fixes 1 --- source/includes/write/bulk-write.php | 4 +- .../class/MongoDBBulkWriteCommandResult.txt | 21 +- .../class/MongoDBClientBulkWrite.txt | 16 +- .../method/MongoDBClient-bulkWrite.txt | 27 +- ...DBClientBulkWrite-createWithCollection.txt | 4 +- .../MongoDBClientBulkWrite-deleteMany.txt | 4 +- .../MongoDBClientBulkWrite-deleteOne.txt | 4 +- .../MongoDBClientBulkWrite-insertOne.txt | 4 +- .../MongoDBClientBulkWrite-replaceOne.txt | 4 +- .../MongoDBClientBulkWrite-updateMany.txt | 4 +- .../MongoDBClientBulkWrite-updateOne.txt | 4 +- .../MongoDBClientBulkWrite-withCollection.txt | 14 +- .../method/MongoDBCollection-bulkWrite.txt | 2 +- source/whats-new.txt | 14 + source/write/bulk-write.txt | 403 +++++++++--------- 15 files changed, 285 insertions(+), 244 deletions(-) diff --git a/source/includes/write/bulk-write.php b/source/includes/write/bulk-write.php index 4ca84dbb..fc8acbaf 100644 --- a/source/includes/write/bulk-write.php +++ b/source/includes/write/bulk-write.php @@ -61,7 +61,7 @@ $bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection); $bulkWrite->insertOne(['name' => 'Mongo Deli', 'cuisine' => 'Sandwiches']); -$bulkWrite = MongoDB\ClientBulkWrite::withCollection($movieCollection); +$bulkWrite = $bulkWrite->withCollection($movieCollection); $bulkWrite->insertOne(['title' => 'The Green Ray', 'year' => 1986]); // end-bulk-client-insert-one @@ -126,7 +126,7 @@ ['upsert' => true], ); -$bulkWrite = MongoDB\ClientBulkWrite::withCollection($movieCollection); +$bulkWrite = $bulkWrite->withCollection($movieCollection); $bulkWrite->insertOne(['title' => 'The Green Ray', 'year' => 1986]); $bulkWrite->deleteMany( ['title' => ['$regex' => 'd{2,}']], diff --git a/source/reference/class/MongoDBBulkWriteCommandResult.txt b/source/reference/class/MongoDBBulkWriteCommandResult.txt index 4fac3c38..923787b2 100644 --- a/source/reference/class/MongoDBBulkWriteCommandResult.txt +++ b/source/reference/class/MongoDBBulkWriteCommandResult.txt @@ -21,20 +21,24 @@ Methods - Description * - ``getInsertedCount()`` - - | Returns the number of documents inserted, if any. + - | Returns the total number of documents inserted by all + insert operations in the bulk write command. * - ``getMatchedCount()`` - - | Returns the number of documents matched during update and replace - operations, if applicable. + - | Returns the total number of documents matched by all + update and replace operations in the bulk write command. * - ``getModifiedCount()`` - - | Returns the number of documents modified, if any. + - | Returns the total number of documents modified by all update + and replace operations in the bulk write command. * - ``getUpsertedCount()`` - - | Returns the number of documents upserted, if any. + - | Returns the total number of documents upserted by all update + and replace operations in the bulk write command. * - ``getDeletedCount()`` - - | Returns the number of documents deleted, if any. + - | Return the total number of documents deleted by all delete + operations in the bulk write command. * - ``getInsertResults()`` - | Returns a map of results of each successful insert operation. Each @@ -53,9 +57,10 @@ Methods a document with information corresponding to the operation. * - ``isAcknowledged()`` - - | Returns a boolean indicating whether the bulk operation was acknowledged. + - | Returns a boolean indicating whether the bulk operation was + acknowledged by the server. See Also -------- -- :ref:`php-bulk-write` +- :ref:`php-client-bulk-write` section of the Bulk Write Operations guide diff --git a/source/reference/class/MongoDBClientBulkWrite.txt b/source/reference/class/MongoDBClientBulkWrite.txt index 9d7f9f7c..7e71473c 100644 --- a/source/reference/class/MongoDBClientBulkWrite.txt +++ b/source/reference/class/MongoDBClientBulkWrite.txt @@ -9,11 +9,17 @@ Definition .. phpclass:: MongoDB\ClientBulkWrite - This class allows you to assemble a bulk write command to pass to - :phpmethod:`MongoDB\Client::bulkWrite()`. + This class enables you to assemble a bulk write command to pass to + :phpmethod:`MongoDB\Client::bulkWrite()` to perform write operations + across multiple namespaces. - This class allows you to specify write operations across multiple - namespaces in the same cluster. + This class is a builder to instantiate a :php:`BulkWriteCommand + ` instance that the library sends to the + server. + + Specify the ``writeConcern`` option as a top-level option to + :phpmethod:`MongoDB\Client::bulkWrite()` instead of in each + individual operation on this class. Methods ------- @@ -42,4 +48,4 @@ Methods See Also -------- -- :ref:`php-bulk-write` +- :ref:`php-client-bulk-write` section of the Bulk Write Operations guide diff --git a/source/reference/method/MongoDBClient-bulkWrite.txt b/source/reference/method/MongoDBClient-bulkWrite.txt index a002eb1e..4a757d6a 100644 --- a/source/reference/method/MongoDBClient-bulkWrite.txt +++ b/source/reference/method/MongoDBClient-bulkWrite.txt @@ -18,7 +18,7 @@ Definition .. phpmethod:: MongoDB\Client::bulkWrite() - Executes multiple write operations across multiple namespaces. + Perform multiple write operations across multiple namespaces. .. code-block:: php @@ -30,21 +30,20 @@ Definition Parameters ---------- -``$bulk`` : :phpclass:`MongoDB\ClientBulkWrite` or ``BulkWriteCommand`` - (reserve for use with the {+extension-short+} only) +``$bulk`` : :phpclass:`MongoDB\ClientBulkWrite` or + :php:`BulkWriteCommand ` + + .. tip:: Prefer ClientBulkWrite API + + We recommend using the ``ClientBulkWrite`` builder class and + methods to specify write operations in a bulk write command instead + of using the ``BulkWriteCommand`` class. Represents the assembled bulk write command or builder. :phpmethod:`MongoDB\Client::bulkWrite()` supports - :phpmethod:`MongoDB\Collection::deleteMany()`, - :phpmethod:`MongoDB\Collection::deleteOne()`, - :phpmethod:`MongoDB\Collection::insertOne()`, - :phpmethod:`MongoDB\Collection::replaceOne()`, - :phpmethod:`MongoDB\Collection::updateMany()`, and - :phpmethod:`MongoDB\Collection::updateOne()` operations. - - The ``writeConcern`` option is specified as a top-level option to - :phpmethod:`MongoDB\Client::bulkWrite()` instead of each individual - operation. + ``deleteMany``, ``deleteOne()``, ``insertOne()``, + ``replaceOne()``, ``updateMany()``, and ``updateOne()`` + operations. ``$options`` : array An array specifying the desired options. @@ -89,7 +88,7 @@ Behavior See Also -------- -- :ref:`php-bulk-write` +- :ref:`php-client-bulk-write` section of the Bulk Write Operations guide - :ref:`php-write` - :phpmethod:`MongoDB\Collection::deleteMany()` - :phpmethod:`MongoDB\Collection::deleteOne()` diff --git a/source/reference/method/MongoDBClientBulkWrite-createWithCollection.txt b/source/reference/method/MongoDBClientBulkWrite-createWithCollection.txt index d021a1ca..c9e9e77e 100644 --- a/source/reference/method/MongoDBClientBulkWrite-createWithCollection.txt +++ b/source/reference/method/MongoDBClientBulkWrite-createWithCollection.txt @@ -15,7 +15,7 @@ Definition .. phpmethod:: MongoDB\ClientBulkWrite::createWithCollection() - Creates an instance of :phpclass:`MongoDB\ClientBulkWrite` from the provided + Create an instance of :phpclass:`MongoDB\ClientBulkWrite` from the provided :phpclass:`MongoDB\Collection` instance. .. code-block:: php @@ -82,4 +82,4 @@ Errors/Exceptions See Also -------- -- :ref:`php-bulk-write` +- :ref:`php-client-bulk-write` section of the Bulk Write Operations guide diff --git a/source/reference/method/MongoDBClientBulkWrite-deleteMany.txt b/source/reference/method/MongoDBClientBulkWrite-deleteMany.txt index 6af3330a..d4376a0d 100644 --- a/source/reference/method/MongoDBClientBulkWrite-deleteMany.txt +++ b/source/reference/method/MongoDBClientBulkWrite-deleteMany.txt @@ -15,7 +15,7 @@ Definition .. phpmethod:: MongoDB\ClientBulkWrite::deleteMany() - Specifies a delete operation in the bulk write command for all + Specify a delete operation in the bulk write command for all matching documents. This method returns the :phpclass:`MongoDB\ClientBulkWrite` instance on which its called. @@ -70,4 +70,4 @@ Behavior See Also -------- -- :ref:`php-bulk-write` +- :ref:`php-client-bulk-write` section of the Bulk Write Operations guide diff --git a/source/reference/method/MongoDBClientBulkWrite-deleteOne.txt b/source/reference/method/MongoDBClientBulkWrite-deleteOne.txt index d0e10ffa..f37a9dc3 100644 --- a/source/reference/method/MongoDBClientBulkWrite-deleteOne.txt +++ b/source/reference/method/MongoDBClientBulkWrite-deleteOne.txt @@ -15,7 +15,7 @@ Definition .. phpmethod:: MongoDB\ClientBulkWrite::deleteOne() - Specifies a delete operation in the bulk write command for the first + Specify a delete operation in the bulk write command for the first matching document. This method returns the :phpclass:`MongoDB\ClientBulkWrite` instance on which its called. @@ -70,4 +70,4 @@ Behavior See Also -------- -- :ref:`php-bulk-write` +- :ref:`php-client-bulk-write` section of the Bulk Write Operations guide diff --git a/source/reference/method/MongoDBClientBulkWrite-insertOne.txt b/source/reference/method/MongoDBClientBulkWrite-insertOne.txt index c2b6ac71..23d9fe29 100644 --- a/source/reference/method/MongoDBClientBulkWrite-insertOne.txt +++ b/source/reference/method/MongoDBClientBulkWrite-insertOne.txt @@ -15,7 +15,7 @@ Definition .. phpmethod:: MongoDB\ClientBulkWrite::insertOne() - Specifies an insert operation in the bulk write command. This method + Specify an insert operation in the bulk write command. This method returns the :phpclass:`MongoDB\ClientBulkWrite` instance on which its called. .. code-block:: php @@ -50,4 +50,4 @@ Behavior See Also -------- -- :ref:`php-bulk-write` +- :ref:`php-client-bulk-write` section of the Bulk Write Operations guide diff --git a/source/reference/method/MongoDBClientBulkWrite-replaceOne.txt b/source/reference/method/MongoDBClientBulkWrite-replaceOne.txt index 87266882..0271279b 100644 --- a/source/reference/method/MongoDBClientBulkWrite-replaceOne.txt +++ b/source/reference/method/MongoDBClientBulkWrite-replaceOne.txt @@ -15,7 +15,7 @@ Definition .. phpmethod:: MongoDB\ClientBulkWrite::replaceOne() - Specifies a replace operation in the bulk write command for the first + Specify a replace operation in the bulk write command for the first matching document. This method returns the :phpclass:`MongoDB\ClientBulkWrite` instance on which its called. @@ -86,4 +86,4 @@ Behavior See Also -------- -- :ref:`php-bulk-write` +- :ref:`php-client-bulk-write` section of the Bulk Write Operations guide diff --git a/source/reference/method/MongoDBClientBulkWrite-updateMany.txt b/source/reference/method/MongoDBClientBulkWrite-updateMany.txt index b417e27b..603e36a3 100644 --- a/source/reference/method/MongoDBClientBulkWrite-updateMany.txt +++ b/source/reference/method/MongoDBClientBulkWrite-updateMany.txt @@ -15,7 +15,7 @@ Definition .. phpmethod:: MongoDB\ClientBulkWrite::updateMany() - Specifies an update operation in the bulk write command for all + Specify an update operation in the bulk write command for all matching documents. This method returns the :phpclass:`MongoDB\ClientBulkWrite` instance on which its called. @@ -93,4 +93,4 @@ Behavior See Also -------- -- :ref:`php-bulk-write` +- :ref:`php-client-bulk-write` section of the Bulk Write Operations guide diff --git a/source/reference/method/MongoDBClientBulkWrite-updateOne.txt b/source/reference/method/MongoDBClientBulkWrite-updateOne.txt index b9b7710c..ff4e516d 100644 --- a/source/reference/method/MongoDBClientBulkWrite-updateOne.txt +++ b/source/reference/method/MongoDBClientBulkWrite-updateOne.txt @@ -15,7 +15,7 @@ Definition .. phpmethod:: MongoDB\ClientBulkWrite::updateOne() - Specifies an update operation in the bulk write command for the first + Specify an update operation in the bulk write command for the first matching document. This method returns the :phpclass:`MongoDB\ClientBulkWrite` instance on which its called. @@ -95,4 +95,4 @@ Behavior See Also -------- -- :ref:`php-bulk-write` +- :ref:`php-client-bulk-write` section of the Bulk Write Operations guide diff --git a/source/reference/method/MongoDBClientBulkWrite-withCollection.txt b/source/reference/method/MongoDBClientBulkWrite-withCollection.txt index 071066e4..6b03afce 100644 --- a/source/reference/method/MongoDBClientBulkWrite-withCollection.txt +++ b/source/reference/method/MongoDBClientBulkWrite-withCollection.txt @@ -15,10 +15,10 @@ Definition .. phpmethod:: MongoDB\ClientBulkWrite::withCollection() - Creates an instance of :phpclass:`MongoDB\ClientBulkWrite` from the provided + Return an instance of :phpclass:`MongoDB\ClientBulkWrite` from the provided :phpclass:`MongoDB\Collection` instance. This method allows you to add subsequent write operations on a different collection than that - which the ``MongoDB\ClientBulkWrite`` was created with. + with which the ``MongoDB\ClientBulkWrite`` was created with. .. code-block:: php @@ -28,14 +28,16 @@ Definition You cannot mix ``Collection`` instances associated with different - ``Manager`` objects. + ``Manager`` objects because the library sends the client bulk + write operation as a command to a single server. Parameters ---------- ``$collection`` : :phpclass:`MongoDB\Collection` - The ``Collection`` instance to set as the target for bulk write - operations. + The ``Collection`` instance to set as the target for write operations + added to the ``ClientBulkWrite`` instance after calling + ``withCollection()``. Errors/Exceptions ----------------- @@ -47,4 +49,4 @@ Errors/Exceptions See Also -------- -- :ref:`php-bulk-write` +- :ref:`php-client-bulk-write` section of the Bulk Write Operations guide diff --git a/source/reference/method/MongoDBCollection-bulkWrite.txt b/source/reference/method/MongoDBCollection-bulkWrite.txt index 4a85ab91..b9367a6f 100644 --- a/source/reference/method/MongoDBCollection-bulkWrite.txt +++ b/source/reference/method/MongoDBCollection-bulkWrite.txt @@ -147,7 +147,7 @@ Behavior See Also -------- -- :ref:`php-bulk-write` +- :ref:`php-coll-bulk-write` section of the Bulk Write Operations guide - :ref:`php-write` - :phpmethod:`MongoDB\Collection::deleteMany()` - :phpmethod:`MongoDB\Collection::deleteOne()` diff --git a/source/whats-new.txt b/source/whats-new.txt index ad60d98c..c4629c80 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -20,6 +20,7 @@ What's New Learn about new features, improvements, and fixes introduced in the following versions of the {+php-library+}: +* :ref:`Version 2.1 ` * :ref:`Version 2.0 ` * :ref:`Version 1.21 ` * :ref:`Version 1.20 ` @@ -27,6 +28,19 @@ following versions of the {+php-library+}: * :ref:`Version 1.18 ` * :ref:`Version 1.17 ` +.. _php-lib-version-2.1: + +What's New in 2.1 +----------------- + +The {+library-short+} v2.1 release includes the following features, +improvements, and fixes: + +- Implements a *client* bulk write API that allows you to perform write + operations on multiple databases and collections in the same call. To learn + more about this feature, see the :ref:`php-client-bulk-write` + section of the Bulk Write Operations guide. + .. _php-lib-version-2.0: What's New in 2.0 diff --git a/source/write/bulk-write.txt b/source/write/bulk-write.txt index 078e96d2..4f713b12 100644 --- a/source/write/bulk-write.txt +++ b/source/write/bulk-write.txt @@ -30,6 +30,15 @@ individual methods, each operation requires its own database call. By using a bulk write operation, you can perform multiple write operations in fewer database calls. You can perform bulk write operations at the following levels: +- :ref:`Client `: If your application connects to + {+mdb-server+} version 8.0 or later, you can use the + ``MongoDB\Client::bulkWrite()`` method to perform bulk write + operations on multiple collections and databases in the same cluster. + This method performs all write operations in one database call. To + learn more about this feature, see the :manual:`Mongo.bulkWrite() + ` reference in the {+mdb-server+} + manual. + - :ref:`Collection `: You can use the ``MongoDB\Collection::bulkWrite()`` method to perform bulk write operations on a single collection. This method makes a database call @@ -37,12 +46,6 @@ fewer database calls. You can perform bulk write operations at the following lev multiple update operations in one call, but makes two separate calls to the database for an insert operation and a replace operation. -- :ref:`Client `: If your application connects to - {+mdb-server+} version 8.0 or later, you can use the - ``MongoDB\Client::bulkWrite()`` method to perform bulk write - operations on multiple collections and databases in the same cluster. - This method performs all write operations in one database call. - Sample Data ~~~~~~~~~~~ @@ -52,177 +55,6 @@ datasets `. To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the :atlas:`Get Started with Atlas ` guide. -.. _php-coll-bulk-write: - -Collection Bulk Write ---------------------- - -To run a bulk write operation, pass an array of write operations to the -:phpmethod:`MongoDB\Collection::bulkWrite()` method. Use the following syntax to -specify the write operations: - -.. code-block:: php - - [ - [ 'deleteMany' => [ $filter ] ], - [ 'deleteOne' => [ $filter ] ], - [ 'insertOne' => [ $document ] ], - [ 'replaceOne' => [ $filter, $replacement, $options ] ], - [ 'updateMany' => [ $filter, $update, $options ] ], - [ 'updateOne' => [ $filter, $update, $options ] ], - ] - -.. tip:: - - To learn more about delete, insert, replace, and update - operations, see the guides in the :ref:`php-write` section. - -When you call the ``bulkWrite()`` method, the library automatically runs the -write operations in the order you specify in the array. To learn how to -instruct ``bulkWrite()`` to run the write operations in an arbitrary order, -see the :ref:`php-bulk-collection-modify` section. - -Example -~~~~~~~ - -This example runs the following write operations on the ``restaurants`` -collection: - -- **Insert operation** to insert a document in which the ``name`` value is - ``'Mongo's Deli'`` - -- **Update operation** to update the ``cuisine`` field of a document in - which the ``name`` value is ``'Mongo's Deli'`` - -- **Delete operation** to delete all documents in which the ``borough`` value - is ``'Manhattan'`` - -.. literalinclude:: /includes/write/bulk-write.php - :start-after: start-run-bulk - :end-before: end-run-bulk - :language: php - :dedent: - -.. note:: - - When the library runs a bulk operation, it uses the write concern of the - target collection. The driver reports all write concern errors after - attempting all operations, regardless of execution order. - -.. _php-bulk-collection-modify: - -Customize Bulk Write Operation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can modify the behavior of the ``MongoDB\Collection::bulkWrite()`` method by -passing an array that specifies option values as a parameter. The following table -describes the options you can set in the array: - -.. list-table:: - :widths: 30 70 - :header-rows: 1 - - * - Option - - Description - - * - ``bypassDocumentValidation`` - - | Specifies whether the operation bypasses document validation. This lets you - modify documents that don't meet the schema validation requirements, if any - exist. For more information about schema validation, see :manual:`Schema - Validation ` in the {+mdb-server+} - manual. - | Defaults to ``false``. - - * - ``codec`` - - | Sets the codec to use for encoding or decoding documents. Bulk writes - use the codec for ``insertOne()`` and ``replaceOne()`` operations. - For more information, see the :ref:`php-codecs` guide. - - * - ``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. - - * - ``ordered`` - - | If set to ``true``: when a single write fails, the operation stops without - performing the remaining writes and throws an exception. - | If set to ``false``: when a single write fails, the operation continues to - attempt the remaining write operations, if any, then throws an exception. - | Defaults to ``true``. - - * - ``comment`` - - | Attaches a comment to the operation. For more information, see the :manual:`insert command - fields ` guide in the - {+mdb-server+} manual. - - * - ``session`` - - | Specifies the client session to associate with the operation. - -The following example calls the ``bulkWrite()`` method to perform an -insert and delete operation and sets the ``ordered`` option to -``false``: - -.. literalinclude:: /includes/write/bulk-write.php - :start-after: start-bulk-options - :end-before: end-bulk-options - :language: php - :dedent: - -If the library runs the insert operation first, one document is deleted. -If it runs the delete operation first, no documents are deleted. - -.. note:: - - Unordered bulk operations do not guarantee order of execution. The order can - differ from the way you list them to optimize the runtime. - -.. _php-bulk-collection-return-value: - -Return Value -~~~~~~~~~~~~ - -The ``MongoDB\Collection::bulkWrite()`` method returns a ``MongoDB\BulkWriteResult`` -object. This class contains the following methods: - -.. list-table:: - :widths: 30 70 - :header-rows: 1 - - * - Method - - Description - - * - ``getDeletedCount()`` - - | Returns the number of documents deleted, if any. - - * - ``getInsertedCount()`` - - | Returns the number of documents inserted, if any. - - * - ``getInsertedIds()`` - - | Returns a map of ``_id`` field values for inserted documents, if any. - - * - ``getMatchedCount()`` - - | Returns the number of documents matched during update and replace - operations, if applicable. - - * - ``getModifiedCount()`` - - | Returns the number of documents modified, if any. - - * - ``getUpsertedCount()`` - - | Returns the number of documents upserted, if any. - - * - ``getUpsertedIds()`` - - | Returns a map of ``_id`` field values for upserted documents, if any. - - * - ``isAcknowledged()`` - - | Returns a boolean indicating whether the bulk operation was acknowledged. - .. _php-client-bulk-write: Client Bulk Write @@ -232,11 +64,10 @@ When using {+library-short+} v2.1 and connecting to a deployment running {+mdb-server+} 8.0 or later, you can use the :phpmethod:`MongoDB\Client::bulkWrite()` method to write to multiple databases and collections in the same cluster. This method performs all write -operations in a single call. To learn more about this feature, see the -:manual:`Mongo.bulkWrite() ` -reference in the {+mdb-server+} manual. +operations in a single call. -First, instantiate a ``MongoDB\ClientBulkWrite`` instance that +First, use the ``MongoDB\ClientBulkWrite`` builder to create a +:php:`BulkWriteCommand ` instance that specifies the write operations to perform. The following code demonstrates how to create a ``ClientBulkWrite`` instance from a ``MongoDB\Collection`` instance by using the ``createWithCollection()`` @@ -265,7 +96,7 @@ the ``withCollection()`` method on the ``ClientBulkWrite`` instance: :emphasize-lines: 2 $movieCollection = $client->sample_mflix->movies; - $bulkWrite = MongoDB\ClientBulkWrite::withCollection($movieCollection); + $bulkWrite = $bulkWrite->withCollection($movieCollection); The following sections show how to create and use the ``ClientBulkWrite`` class to specify write operations @@ -478,20 +309,24 @@ object. This class contains the following methods: - Description * - ``getInsertedCount()`` - - | Returns the number of documents inserted, if any. + - | Returns the total number of documents inserted by all + insert operations in the bulk write command. * - ``getMatchedCount()`` - - | Returns the number of documents matched during update and replace - operations, if applicable. + - | Returns the total number of documents matched by all + update and replace operations in the bulk write command. * - ``getModifiedCount()`` - - | Returns the number of documents modified, if any. + - | Returns the total number of documents modified by all update + and replace operations in the bulk write command. * - ``getUpsertedCount()`` - - | Returns the number of documents upserted, if any. + - | Returns the total number of documents upserted by all update + and replace operations in the bulk write command. * - ``getDeletedCount()`` - - | Returns the number of documents deleted, if any. + - | Return the total number of documents deleted by all delete + operations in the bulk write command. * - ``getInsertResults()`` - | Returns a map of results of each successful insert operation. Each @@ -510,7 +345,187 @@ object. This class contains the following methods: a document with information corresponding to the operation. * - ``isAcknowledged()`` - - | Returns a boolean indicating whether the bulk operation was acknowledged. + - | Returns a boolean indicating whether the bulk operation was + acknowledged by the server. + +.. _php-coll-bulk-write: + +Collection Bulk Write +--------------------- + +To run a bulk write operation, pass an array of write operations to the +:phpmethod:`MongoDB\Collection::bulkWrite()` method. Use the following syntax to +specify the write operations: + +.. code-block:: php + + [ + [ 'deleteMany' => [ $filter ] ], + [ 'deleteOne' => [ $filter ] ], + [ 'insertOne' => [ $document ] ], + [ 'replaceOne' => [ $filter, $replacement, $options ] ], + [ 'updateMany' => [ $filter, $update, $options ] ], + [ 'updateOne' => [ $filter, $update, $options ] ], + ] + +.. tip:: + + To learn more about delete, insert, replace, and update + operations, see the guides in the :ref:`php-write` section. + +When you call the ``bulkWrite()`` method, the library automatically runs the +write operations in the order you specify in the array. To learn how to +instruct ``bulkWrite()`` to run the write operations in an arbitrary order, +see the :ref:`php-bulk-collection-modify` section. + +Example +~~~~~~~ + +This example runs the following write operations on the ``restaurants`` +collection: + +- **Insert operation** to insert a document in which the ``name`` value is + ``'Mongo's Deli'`` + +- **Update operation** to update the ``cuisine`` field of a document in + which the ``name`` value is ``'Mongo's Deli'`` + +- **Delete operation** to delete all documents in which the ``borough`` value + is ``'Manhattan'`` + +.. literalinclude:: /includes/write/bulk-write.php + :start-after: start-run-bulk + :end-before: end-run-bulk + :language: php + :dedent: + +.. note:: + + When the library runs a bulk operation, it uses the write concern of the + target collection. The driver reports all write concern errors after + attempting all operations, regardless of execution order. + +.. _php-bulk-collection-modify: + +Customize Bulk Write Operation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can modify the behavior of the ``MongoDB\Collection::bulkWrite()`` method by +passing an array that specifies option values as a parameter. The following table +describes the options you can set in the array: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Option + - Description + + * - ``bypassDocumentValidation`` + - | Specifies whether the operation bypasses document validation. This lets you + modify documents that don't meet the schema validation requirements, if any + exist. For more information about schema validation, see :manual:`Schema + Validation ` in the {+mdb-server+} + manual. + | Defaults to ``false``. + + * - ``codec`` + - | Sets the codec to use for encoding or decoding documents. Bulk writes + use the codec for ``insertOne()`` and ``replaceOne()`` operations. + For more information, see the :ref:`php-codecs` guide. + + * - ``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. + + * - ``ordered`` + - | If set to ``true``: when a single write fails, the operation stops without + performing the remaining writes and throws an exception. + | If set to ``false``: when a single write fails, the operation continues to + attempt the remaining write operations, if any, then throws an exception. + | Defaults to ``true``. + + * - ``comment`` + - | Attaches a comment to the operation. For more information, see the :manual:`insert command + fields ` guide in the + {+mdb-server+} manual. + + * - ``session`` + - | Specifies the client session to associate with the operation. + +The following example calls the ``bulkWrite()`` method to perform an +insert and delete operation and sets the ``ordered`` option to +``false``: + +.. literalinclude:: /includes/write/bulk-write.php + :start-after: start-bulk-options + :end-before: end-bulk-options + :language: php + :dedent: + +If the library runs the insert operation first, one document is deleted. +If it runs the delete operation first, no documents are deleted. + +.. note:: + + Unordered bulk operations do not guarantee order of execution. The order can + differ from the way you list them to optimize the runtime. + +.. _php-bulk-collection-return-value: + +Return Value +~~~~~~~~~~~~ + +The ``MongoDB\Collection::bulkWrite()`` method returns a ``MongoDB\BulkWriteResult`` +object. This class contains the following methods: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Method + - Description + + * - ``getInsertedCount()`` + - | Returns the total number of documents inserted by all + insert operations in the bulk write command. + + * - ``getInsertedIds()`` + - | Returns a map of ``_id`` field values for documents + inserted by all insert operations in the bulk write command. + + * - ``getMatchedCount()`` + - | Returns the total number of documents matched by all + update and replace operations in the bulk write command. + + * - ``getModifiedCount()`` + - | Returns the total number of documents modified by all update + and replace operations in the bulk write command. + + * - ``getUpsertedCount()`` + - | Returns the total number of documents upserted by all update + and replace operations in the bulk write command. + + * - ``getUpsertedIds()`` + - | Returns a map of ``_id`` field values for documents + upserted by all update and replace operations in the bulk write + command. + + * - ``getDeletedCount()`` + - | Return the total number of documents deleted by all delete + operations in the bulk write command. + + * - ``isAcknowledged()`` + - | Returns a boolean indicating whether the bulk operation was + acknowledged by the server. Additional Information ---------------------- @@ -528,13 +543,13 @@ API Documentation To learn more about any of the methods or types discussed in this guide, see the following API documentation: -- Collection Bulk Write - - - :phpmethod:`MongoDB\Collection::bulkWrite()` - - :phpclass:`MongoDB\BulkWriteResult` - - Client Bulk Write - :phpclass:`MongoDB\ClientBulkWrite` - :phpmethod:`MongoDB\Client::bulkWrite()` - :phpclass:`MongoDB\BulkWriteCommandResult` + +- Collection Bulk Write + + - :phpmethod:`MongoDB\Collection::bulkWrite()` + - :phpclass:`MongoDB\BulkWriteResult` From 5cbb50862b0199f4563b8d447682b45cf7190235 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 20 May 2025 15:35:14 -0400 Subject: [PATCH 04/12] upgrade composer package vs --- composer/composer.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/composer/composer.json b/composer/composer.json index 8892815e..c85d1216 100644 --- a/composer/composer.json +++ b/composer/composer.json @@ -2,8 +2,8 @@ "name": "mongodb/docs-php-library", "description": "MongoDB PHP Library Documentation", "require": { - "ext-mongodb": "^1.20", - "mongodb/mongodb": "^1.20" + "ext-mongodb": "^2.0", + "mongodb/mongodb": "^2.0" }, "require-dev": { "doctrine/coding-standard": "^12.0", From d14ca58d78f306ce498eefa96ce8173d4f72b6b1 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 20 May 2025 15:41:12 -0400 Subject: [PATCH 05/12] JT PR fixes 2 --- source/reference/class/MongoDBClientBulkWrite.txt | 8 ++++---- source/reference/method/MongoDBClient-bulkWrite.txt | 4 +++- .../method/MongoDBClientBulkWrite-withCollection.txt | 6 +++--- 3 files changed, 10 insertions(+), 8 deletions(-) diff --git a/source/reference/class/MongoDBClientBulkWrite.txt b/source/reference/class/MongoDBClientBulkWrite.txt index 7e71473c..320ee282 100644 --- a/source/reference/class/MongoDBClientBulkWrite.txt +++ b/source/reference/class/MongoDBClientBulkWrite.txt @@ -9,11 +9,11 @@ Definition .. phpclass:: MongoDB\ClientBulkWrite - This class enables you to assemble a bulk write command to pass to - :phpmethod:`MongoDB\Client::bulkWrite()` to perform write operations - across multiple namespaces. + This class enables you to assemble a bulk write command that you + pass to :phpmethod:`MongoDB\Client::bulkWrite()` to perform write + operations across multiple namespaces. - This class is a builder to instantiate a :php:`BulkWriteCommand + ``ClientBulkWrite`` is a builder class to create a :php:`BulkWriteCommand ` instance that the library sends to the server. diff --git a/source/reference/method/MongoDBClient-bulkWrite.txt b/source/reference/method/MongoDBClient-bulkWrite.txt index 4a757d6a..3c34088d 100644 --- a/source/reference/method/MongoDBClient-bulkWrite.txt +++ b/source/reference/method/MongoDBClient-bulkWrite.txt @@ -37,7 +37,9 @@ Parameters We recommend using the ``ClientBulkWrite`` builder class and methods to specify write operations in a bulk write command instead - of using the ``BulkWriteCommand`` class. + of using the ``BulkWriteCommand`` class. ``ClientBulkWrite`` + provides a fluent API with methods similar to CRUD methods from the + :phpclass:`MongoDB\Collection` class. Represents the assembled bulk write command or builder. :phpmethod:`MongoDB\Client::bulkWrite()` supports diff --git a/source/reference/method/MongoDBClientBulkWrite-withCollection.txt b/source/reference/method/MongoDBClientBulkWrite-withCollection.txt index 6b03afce..ebc68723 100644 --- a/source/reference/method/MongoDBClientBulkWrite-withCollection.txt +++ b/source/reference/method/MongoDBClientBulkWrite-withCollection.txt @@ -26,10 +26,10 @@ Definition Collection $collection, ): self - You cannot mix ``Collection`` instances associated with different - ``Manager`` objects because the library sends the client bulk - write operation as a command to a single server. + ``Manager`` objects when calling this method on a ``ClientBulkWrite`` + instance. This is because the library sends the completed + ``BulkWriteCommand`` to a single server. Parameters ---------- From a29dfde0b890098c0c712bf760849a65ca4a1029 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 20 May 2025 15:48:12 -0400 Subject: [PATCH 06/12] small fix --- source/reference/class/MongoDBBulkWriteCommandResult.txt | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/source/reference/class/MongoDBBulkWriteCommandResult.txt b/source/reference/class/MongoDBBulkWriteCommandResult.txt index 923787b2..4bd25e71 100644 --- a/source/reference/class/MongoDBBulkWriteCommandResult.txt +++ b/source/reference/class/MongoDBBulkWriteCommandResult.txt @@ -60,6 +60,11 @@ Methods - | Returns a boolean indicating whether the bulk operation was acknowledged by the server. +To learn more about the information returned from the server when you +perform a client bulk write operation, see the :manual:`Output +` section of the +``Mongo.bulkWrite`` shell method reference. + See Also -------- From 6d3217e5b0a1acac6bac4608bee5030bfc9b6782 Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 21 May 2025 09:56:59 -0400 Subject: [PATCH 07/12] JT PR fixes 3 --- composer/composer.json | 4 ++-- .../MongoDBClientBulkWrite-createWithCollection.txt | 9 +++++---- .../method/MongoDBClientBulkWrite-deleteMany.txt | 2 -- .../method/MongoDBClientBulkWrite-deleteOne.txt | 2 -- .../method/MongoDBClientBulkWrite-replaceOne.txt | 2 -- .../method/MongoDBClientBulkWrite-updateMany.txt | 7 ++----- .../method/MongoDBClientBulkWrite-updateOne.txt | 8 +++----- .../MongoDBClientBulkWrite-withCollection.txt | 13 +++++++++---- source/whats-new.txt | 2 +- 9 files changed, 22 insertions(+), 27 deletions(-) diff --git a/composer/composer.json b/composer/composer.json index c85d1216..a76d24ba 100644 --- a/composer/composer.json +++ b/composer/composer.json @@ -2,8 +2,8 @@ "name": "mongodb/docs-php-library", "description": "MongoDB PHP Library Documentation", "require": { - "ext-mongodb": "^2.0", - "mongodb/mongodb": "^2.0" + "ext-mongodb": "^2.1", + "mongodb/mongodb": "^2.1" }, "require-dev": { "doctrine/coding-standard": "^12.0", diff --git a/source/reference/method/MongoDBClientBulkWrite-createWithCollection.txt b/source/reference/method/MongoDBClientBulkWrite-createWithCollection.txt index c9e9e77e..dd4b0c26 100644 --- a/source/reference/method/MongoDBClientBulkWrite-createWithCollection.txt +++ b/source/reference/method/MongoDBClientBulkWrite-createWithCollection.txt @@ -15,8 +15,11 @@ Definition .. phpmethod:: MongoDB\ClientBulkWrite::createWithCollection() - Create an instance of :phpclass:`MongoDB\ClientBulkWrite` from the provided - :phpclass:`MongoDB\Collection` instance. + Create an instance of the :phpclass:`MongoDB\ClientBulkWrite` builder + from the provided :phpclass:`MongoDB\Collection` instance. You can + add write operations to the ``ClientBulkWrite`` to create a new + :php:`BulkWriteCommand ` that the + library sends to the server. .. code-block:: php @@ -52,8 +55,6 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/option-requires-4.4.rst - * - let - array|object - .. include:: /includes/extracts/common-option-let.rst diff --git a/source/reference/method/MongoDBClientBulkWrite-deleteMany.txt b/source/reference/method/MongoDBClientBulkWrite-deleteMany.txt index d4376a0d..13846235 100644 --- a/source/reference/method/MongoDBClientBulkWrite-deleteMany.txt +++ b/source/reference/method/MongoDBClientBulkWrite-deleteMany.txt @@ -51,8 +51,6 @@ Parameters - string|array|object - .. include:: /includes/extracts/common-option-hint.rst - .. include:: /includes/extracts/option-requires-4.4.rst - Errors/Exceptions ----------------- diff --git a/source/reference/method/MongoDBClientBulkWrite-deleteOne.txt b/source/reference/method/MongoDBClientBulkWrite-deleteOne.txt index f37a9dc3..9684e56d 100644 --- a/source/reference/method/MongoDBClientBulkWrite-deleteOne.txt +++ b/source/reference/method/MongoDBClientBulkWrite-deleteOne.txt @@ -51,8 +51,6 @@ Parameters - string|array|object - .. include:: /includes/extracts/common-option-hint.rst - .. include:: /includes/extracts/option-requires-4.4.rst - Errors/Exceptions ----------------- diff --git a/source/reference/method/MongoDBClientBulkWrite-replaceOne.txt b/source/reference/method/MongoDBClientBulkWrite-replaceOne.txt index 0271279b..c9d3614b 100644 --- a/source/reference/method/MongoDBClientBulkWrite-replaceOne.txt +++ b/source/reference/method/MongoDBClientBulkWrite-replaceOne.txt @@ -55,8 +55,6 @@ Parameters - string|array|object - .. include:: /includes/extracts/common-option-hint.rst - .. include:: /includes/extracts/option-requires-4.2.rst - * - sort - array|object - The sort specification for the ordering of the matched diff --git a/source/reference/method/MongoDBClientBulkWrite-updateMany.txt b/source/reference/method/MongoDBClientBulkWrite-updateMany.txt index 603e36a3..3daa626a 100644 --- a/source/reference/method/MongoDBClientBulkWrite-updateMany.txt +++ b/source/reference/method/MongoDBClientBulkWrite-updateMany.txt @@ -36,9 +36,8 @@ Parameters ``$update`` : array|object Specifies the field and value combinations to update and any relevant update operators. ``$update`` uses MongoDB's :manual:`update operators `. - Starting with MongoDB 4.2, you can pass an :manual:`aggregation pipeline - ` - as this parameter. + You can pass an :manual:`aggregation pipeline + ` as this parameter. ``$options`` : array An array specifying the desired options. @@ -68,8 +67,6 @@ Parameters - string|array|object - .. include:: /includes/extracts/common-option-hint.rst - .. include:: /includes/extracts/option-requires-4.2.rst - * - upsert - boolean - If set to ``true``, creates a new document when no document matches the diff --git a/source/reference/method/MongoDBClientBulkWrite-updateOne.txt b/source/reference/method/MongoDBClientBulkWrite-updateOne.txt index ff4e516d..2de70ed3 100644 --- a/source/reference/method/MongoDBClientBulkWrite-updateOne.txt +++ b/source/reference/method/MongoDBClientBulkWrite-updateOne.txt @@ -36,9 +36,9 @@ Parameters ``$update`` : array|object Specifies the field and value combinations to update and any relevant update operators. ``$update`` uses MongoDB's :manual:`update operators - `. Starting with MongoDB 4.2, an `aggregation - pipeline `_ - can be passed as this parameter. + `. You can pass an :manual:`aggregation pipeline + ` as + this parameter. ``$options`` : array An array specifying the desired options. @@ -64,8 +64,6 @@ Parameters - string|array|object - .. include:: /includes/extracts/common-option-hint.rst - .. include:: /includes/extracts/option-requires-4.2.rst - * - sort - array|object - The sort specification for the ordering of the matched diff --git a/source/reference/method/MongoDBClientBulkWrite-withCollection.txt b/source/reference/method/MongoDBClientBulkWrite-withCollection.txt index ebc68723..459eca73 100644 --- a/source/reference/method/MongoDBClientBulkWrite-withCollection.txt +++ b/source/reference/method/MongoDBClientBulkWrite-withCollection.txt @@ -15,10 +15,15 @@ Definition .. phpmethod:: MongoDB\ClientBulkWrite::withCollection() - Return an instance of :phpclass:`MongoDB\ClientBulkWrite` from the provided - :phpclass:`MongoDB\Collection` instance. This method allows you to - add subsequent write operations on a different collection than that - with which the ``MongoDB\ClientBulkWrite`` was created with. + Return an updated instance of :phpclass:`MongoDB\ClientBulkWrite` + from the provided :phpclass:`MongoDB\Collection` instance. This + method allows you to add subsequent write operations on a different + collection than that with which the ``ClientBulkWrite`` was created + with. + + This method does not build a new :php:`BulkWriteCommand + ` and does not edit the + ``ClientBulkWrite`` instance in place. .. code-block:: php diff --git a/source/whats-new.txt b/source/whats-new.txt index c4629c80..e7421ddd 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -36,7 +36,7 @@ What's New in 2.1 The {+library-short+} v2.1 release includes the following features, improvements, and fixes: -- Implements a *client* bulk write API that allows you to perform write +- Adds a *client* bulk write API to perform write operations on multiple databases and collections in the same call. To learn more about this feature, see the :ref:`php-client-bulk-write` section of the Bulk Write Operations guide. From 5b07d53278e9966218f00eab0eb24d0292e4cb69 Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 21 May 2025 09:59:20 -0400 Subject: [PATCH 08/12] remove reference to writeconcern option --- source/reference/class/MongoDBClientBulkWrite.txt | 4 ---- 1 file changed, 4 deletions(-) diff --git a/source/reference/class/MongoDBClientBulkWrite.txt b/source/reference/class/MongoDBClientBulkWrite.txt index 320ee282..b197a2f5 100644 --- a/source/reference/class/MongoDBClientBulkWrite.txt +++ b/source/reference/class/MongoDBClientBulkWrite.txt @@ -17,10 +17,6 @@ Definition ` instance that the library sends to the server. - Specify the ``writeConcern`` option as a top-level option to - :phpmethod:`MongoDB\Client::bulkWrite()` instead of in each - individual operation on this class. - Methods ------- From 1b2d7e0c23e8304bb8b131ecd746117049025248 Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 21 May 2025 10:42:11 -0400 Subject: [PATCH 09/12] add return values sections --- .../method/MongoDBClientBulkWrite-createWithCollection.txt | 6 ++++++ .../method/MongoDBClientBulkWrite-withCollection.txt | 6 ++++++ 2 files changed, 12 insertions(+) diff --git a/source/reference/method/MongoDBClientBulkWrite-createWithCollection.txt b/source/reference/method/MongoDBClientBulkWrite-createWithCollection.txt index dd4b0c26..e4fc40ce 100644 --- a/source/reference/method/MongoDBClientBulkWrite-createWithCollection.txt +++ b/source/reference/method/MongoDBClientBulkWrite-createWithCollection.txt @@ -73,6 +73,12 @@ Parameters - boolean - Specifies whether to return verbose results. The default is ``false``. +Return Values +------------- + +A new ``ClientBulkWrite`` object with an empty ``BulkWriteCommand`` +specification. + Errors/Exceptions ----------------- diff --git a/source/reference/method/MongoDBClientBulkWrite-withCollection.txt b/source/reference/method/MongoDBClientBulkWrite-withCollection.txt index 459eca73..6aa9effc 100644 --- a/source/reference/method/MongoDBClientBulkWrite-withCollection.txt +++ b/source/reference/method/MongoDBClientBulkWrite-withCollection.txt @@ -44,6 +44,12 @@ Parameters added to the ``ClientBulkWrite`` instance after calling ``withCollection()``. +Return Values +------------- + +A new ``ClientBulkWrite`` object with the same ``BulkWriteCommand`` +specification but an updated target namespace. + Errors/Exceptions ----------------- From b4005d9d10aa479b4d3ab98b0dc848f1fe429cea Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 21 May 2025 10:43:03 -0400 Subject: [PATCH 10/12] object -> instance --- .../method/MongoDBClientBulkWrite-createWithCollection.txt | 2 +- .../reference/method/MongoDBClientBulkWrite-withCollection.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/source/reference/method/MongoDBClientBulkWrite-createWithCollection.txt b/source/reference/method/MongoDBClientBulkWrite-createWithCollection.txt index e4fc40ce..98c2abcb 100644 --- a/source/reference/method/MongoDBClientBulkWrite-createWithCollection.txt +++ b/source/reference/method/MongoDBClientBulkWrite-createWithCollection.txt @@ -76,7 +76,7 @@ Parameters Return Values ------------- -A new ``ClientBulkWrite`` object with an empty ``BulkWriteCommand`` +A new ``ClientBulkWrite`` instance with an empty ``BulkWriteCommand`` specification. Errors/Exceptions diff --git a/source/reference/method/MongoDBClientBulkWrite-withCollection.txt b/source/reference/method/MongoDBClientBulkWrite-withCollection.txt index 6aa9effc..24823322 100644 --- a/source/reference/method/MongoDBClientBulkWrite-withCollection.txt +++ b/source/reference/method/MongoDBClientBulkWrite-withCollection.txt @@ -47,7 +47,7 @@ Parameters Return Values ------------- -A new ``ClientBulkWrite`` object with the same ``BulkWriteCommand`` +A new ``ClientBulkWrite`` instance with the same ``BulkWriteCommand`` specification but an updated target namespace. Errors/Exceptions From f25264d1cf351bd2f8ba99c05de4cca9ab1acb7b Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 21 May 2025 15:45:30 -0400 Subject: [PATCH 11/12] NR PR fixes 1 --- .../includes/extracts-bulkwriteexception.yaml | 6 +- source/includes/extracts-error.yaml | 4 +- source/includes/write/bulk-write.php | 23 +++- .../class/MongoDBBulkWriteCommandResult.txt | 6 +- .../class/MongoDBBulkWriteResult.txt | 4 +- .../method/MongoDBClient-bulkWrite.txt | 2 +- ...DBClientBulkWrite-createWithCollection.txt | 18 +-- .../MongoDBClientBulkWrite-deleteMany.txt | 2 +- .../MongoDBClientBulkWrite-deleteOne.txt | 2 +- .../MongoDBClientBulkWrite-insertOne.txt | 2 +- .../MongoDBClientBulkWrite-replaceOne.txt | 2 +- .../MongoDBClientBulkWrite-updateMany.txt | 4 +- .../MongoDBClientBulkWrite-updateOne.txt | 4 +- .../MongoDBClientBulkWrite-withCollection.txt | 3 +- .../method/MongoDBCollection-bulkWrite.txt | 4 +- .../method/MongoDBCollection-insertMany.txt | 4 +- source/write/bulk-write.txt | 103 ++++++++++-------- source/write/replace.txt | 3 +- source/write/update.txt | 3 +- 19 files changed, 116 insertions(+), 83 deletions(-) diff --git a/source/includes/extracts-bulkwriteexception.yaml b/source/includes/extracts-bulkwriteexception.yaml index 75062e6a..a19fce00 100644 --- a/source/includes/extracts-bulkwriteexception.yaml +++ b/source/includes/extracts-bulkwriteexception.yaml @@ -1,7 +1,7 @@ ref: bulkwriteexception-result content: | If a :php:`MongoDB\Driver\Exception\BulkWriteException - ` is thrown, users should call + ` is thrown, you can call :php:`getWriteResult() ` and inspect the returned :php:`MongoDB\Driver\WriteResult ` object to determine the nature of the error. @@ -14,7 +14,7 @@ content: | ref: bulkwriteexception-client-result content: | If a :php:`MongoDB\Driver\Exception\BulkWriteCommandException - ` is thrown, users should call + ` is thrown, you can call :php:`getWriteErrors() ` and inspect the information in the returned array to determine the nature of the error. @@ -25,7 +25,7 @@ content: | --- ref: bulkwriteexception-ordered content: | - In the case of a bulk write, the result may indicate multiple successful write + In the case of a bulk write, the result might indicate multiple successful write operations and/or errors. If the ``ordered`` option is ``true``, some operations may have succeeded before the first error was encountered and the exception thrown. If the ``ordered`` option is ``false``, multiple errors may diff --git a/source/includes/extracts-error.yaml b/source/includes/extracts-error.yaml index cda75f1d..d829b0ec 100644 --- a/source/includes/extracts-error.yaml +++ b/source/includes/extracts-error.yaml @@ -2,7 +2,7 @@ ref: error-driver-bulkwriteexception content: | :php:`MongoDB\Driver\Exception\BulkWriteException ` for errors related to the write - operation. Users should inspect the value returned by :php:`getWriteResult() + operation. You can inspect the value returned by :php:`getWriteResult() ` to determine the nature of the error. --- @@ -10,7 +10,7 @@ ref: error-driver-client-bulkwriteexception content: | :php:`MongoDB\Driver\Exception\BulkWriteCommandException ` for errors related to the write - operation. Users should inspect the value returned by :php:`getWriteErrors() + operation. You can inspect the value returned by :php:`getWriteErrors() ` to determine the nature of the error. --- diff --git a/source/includes/write/bulk-write.php b/source/includes/write/bulk-write.php index fc8acbaf..2e0f9612 100644 --- a/source/includes/write/bulk-write.php +++ b/source/includes/write/bulk-write.php @@ -117,31 +117,48 @@ // start-bulk-client $restaurantCollection = $client->sample_restaurants->restaurants; $movieCollection = $client->sample_mflix->movies; - +// Creates the bulk write command and sets the target namespace. $bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection); +// Specifies insertion of one document. $bulkWrite->insertOne(['name' => 'Mongo Deli', 'cuisine' => 'Sandwiches']); +// Specifies a `$set` update to one document with the upsert option +// enabled. $bulkWrite->updateOne( ['name' => 'Dandelion Bakery'], ['$set' => ['grade' => 'B+']], ['upsert' => true], ); - +// Changes the target namespace. $bulkWrite = $bulkWrite->withCollection($movieCollection); +// Specifies insertion of one document. $bulkWrite->insertOne(['title' => 'The Green Ray', 'year' => 1986]); +// Specifies deletion of documents in which `title` has two consective +// 'd' characters. $bulkWrite->deleteMany( ['title' => ['$regex' => 'd{2,}']], ); +// Specifies replacement of one document. $bulkWrite->replaceOne( ['runtime' => ['$gte' => 200]], ['title' => 'Seven Samurai', 'runtime' => 203], ); +// Performs the bulk write operation. $result = $client->bulkWrite($bulkWrite); +// Prints a summary of results. echo 'Inserted documents: ', $result->getInsertedCount(), PHP_EOL; echo 'Modified documents: ', $result->getModifiedCount(), PHP_EOL; echo 'Deleted documents: ', $result->getDeletedCount(), PHP_EOL; // end-bulk-client // start-bulk-client-options -$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($collection, ['ordered' => false]); +$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection( + $restaurantCollection, + ['ordered' => false] +); // end-bulk-client-options + +// start-bulk-client-unordered-behavior +$bulkWrite->insertOne(['_id' => 4045, 'title' => 'The Green Ray']); +$bulkWrite->deleteOne(['_id' => 4045]); +// end-bulk-client-unordered-behavior diff --git a/source/reference/class/MongoDBBulkWriteCommandResult.txt b/source/reference/class/MongoDBBulkWriteCommandResult.txt index 4bd25e71..f92f04d2 100644 --- a/source/reference/class/MongoDBBulkWriteCommandResult.txt +++ b/source/reference/class/MongoDBBulkWriteCommandResult.txt @@ -7,7 +7,7 @@ Definition .. phpclass:: MongoDB\BulkWriteCommandResult - This class contains information about an executed client bulk write operation. It + This class contains information about a completed client bulk write operation. It is returned from :phpmethod:`MongoDB\Client::bulkWrite()`. Methods @@ -57,8 +57,8 @@ Methods a document with information corresponding to the operation. * - ``isAcknowledged()`` - - | Returns a boolean indicating whether the bulk operation was - acknowledged by the server. + - | Returns a boolean indicating whether the server acknowledged + the bulk operation. To learn more about the information returned from the server when you perform a client bulk write operation, see the :manual:`Output diff --git a/source/reference/class/MongoDBBulkWriteResult.txt b/source/reference/class/MongoDBBulkWriteResult.txt index 2e8c78cf..14c87c85 100644 --- a/source/reference/class/MongoDBBulkWriteResult.txt +++ b/source/reference/class/MongoDBBulkWriteResult.txt @@ -7,7 +7,7 @@ Definition .. phpclass:: MongoDB\BulkWriteResult - This class contains information about an executed bulk write operation. It + This class contains information about a completed bulk write operation. It encapsulates a :php:`MongoDB\Driver\WriteResult ` object and is returned from :phpmethod:`MongoDB\Collection::bulkWrite()`. @@ -33,4 +33,4 @@ Methods - :phpmethod:`MongoDB\BulkWriteResult::getModifiedCount()` - :phpmethod:`MongoDB\BulkWriteResult::getUpsertedCount()` - :phpmethod:`MongoDB\BulkWriteResult::getUpsertedIds()` -- :phpmethod:`MongoDB\BulkWriteResult::isAcknowledged()` \ No newline at end of file +- :phpmethod:`MongoDB\BulkWriteResult::isAcknowledged()` diff --git a/source/reference/method/MongoDBClient-bulkWrite.txt b/source/reference/method/MongoDBClient-bulkWrite.txt index 3c34088d..6e3ab31b 100644 --- a/source/reference/method/MongoDBClient-bulkWrite.txt +++ b/source/reference/method/MongoDBClient-bulkWrite.txt @@ -43,7 +43,7 @@ Parameters Represents the assembled bulk write command or builder. :phpmethod:`MongoDB\Client::bulkWrite()` supports - ``deleteMany``, ``deleteOne()``, ``insertOne()``, + ``deleteMany()``, ``deleteOne()``, ``insertOne()``, ``replaceOne()``, ``updateMany()``, and ``updateOne()`` operations. diff --git a/source/reference/method/MongoDBClientBulkWrite-createWithCollection.txt b/source/reference/method/MongoDBClientBulkWrite-createWithCollection.txt index 98c2abcb..478c70a8 100644 --- a/source/reference/method/MongoDBClientBulkWrite-createWithCollection.txt +++ b/source/reference/method/MongoDBClientBulkWrite-createWithCollection.txt @@ -48,8 +48,10 @@ Parameters * - bypassDocumentValidation - boolean - - If ``true``, allows the write operation to circumvent document level - validation. Defaults to ``false``. + - If ``true``: the write operation ignores document level + validation. + + The default is ``false``. * - comment - mixed @@ -61,17 +63,19 @@ Parameters * - ordered - boolean - - If ``true``: when a single write fails, the operation stops without - performing the remaining writes and throws an exception. + - If ``true``: When a single write fails, the operation stops without + performing the remaining writes and returns an exception. - If ``false``: when a single write fails, the operation continues - with the remaining writes, if any, and throws an exception. + If ``false``: When a single write fails, the operation continues + with the remaining writes, if any, and returns an exception. The default is ``true``. * - verboseResults - boolean - - Specifies whether to return verbose results. The default is ``false``. + - Specifies whether to return verbose results. + + The default is ``false``. Return Values ------------- diff --git a/source/reference/method/MongoDBClientBulkWrite-deleteMany.txt b/source/reference/method/MongoDBClientBulkWrite-deleteMany.txt index 13846235..654d7c40 100644 --- a/source/reference/method/MongoDBClientBulkWrite-deleteMany.txt +++ b/source/reference/method/MongoDBClientBulkWrite-deleteMany.txt @@ -17,7 +17,7 @@ Definition Specify a delete operation in the bulk write command for all matching documents. This method returns the - :phpclass:`MongoDB\ClientBulkWrite` instance on which its called. + :phpclass:`MongoDB\ClientBulkWrite` instance on which it's called. .. code-block:: php diff --git a/source/reference/method/MongoDBClientBulkWrite-deleteOne.txt b/source/reference/method/MongoDBClientBulkWrite-deleteOne.txt index 9684e56d..0358af9f 100644 --- a/source/reference/method/MongoDBClientBulkWrite-deleteOne.txt +++ b/source/reference/method/MongoDBClientBulkWrite-deleteOne.txt @@ -17,7 +17,7 @@ Definition Specify a delete operation in the bulk write command for the first matching document. This method returns the - :phpclass:`MongoDB\ClientBulkWrite` instance on which its called. + :phpclass:`MongoDB\ClientBulkWrite` instance on which it's called. .. code-block:: php diff --git a/source/reference/method/MongoDBClientBulkWrite-insertOne.txt b/source/reference/method/MongoDBClientBulkWrite-insertOne.txt index 23d9fe29..74ffa769 100644 --- a/source/reference/method/MongoDBClientBulkWrite-insertOne.txt +++ b/source/reference/method/MongoDBClientBulkWrite-insertOne.txt @@ -16,7 +16,7 @@ Definition .. phpmethod:: MongoDB\ClientBulkWrite::insertOne() Specify an insert operation in the bulk write command. This method - returns the :phpclass:`MongoDB\ClientBulkWrite` instance on which its called. + returns the :phpclass:`MongoDB\ClientBulkWrite` instance on which it's called. .. code-block:: php diff --git a/source/reference/method/MongoDBClientBulkWrite-replaceOne.txt b/source/reference/method/MongoDBClientBulkWrite-replaceOne.txt index c9d3614b..dcf81e66 100644 --- a/source/reference/method/MongoDBClientBulkWrite-replaceOne.txt +++ b/source/reference/method/MongoDBClientBulkWrite-replaceOne.txt @@ -17,7 +17,7 @@ Definition Specify a replace operation in the bulk write command for the first matching document. This method returns the - :phpclass:`MongoDB\ClientBulkWrite` instance on which its called. + :phpclass:`MongoDB\ClientBulkWrite` instance on which it's called. .. code-block:: php diff --git a/source/reference/method/MongoDBClientBulkWrite-updateMany.txt b/source/reference/method/MongoDBClientBulkWrite-updateMany.txt index 3daa626a..e4b1d637 100644 --- a/source/reference/method/MongoDBClientBulkWrite-updateMany.txt +++ b/source/reference/method/MongoDBClientBulkWrite-updateMany.txt @@ -17,7 +17,7 @@ Definition Specify an update operation in the bulk write command for all matching documents. This method returns the - :phpclass:`MongoDB\ClientBulkWrite` instance on which its called. + :phpclass:`MongoDB\ClientBulkWrite` instance on which it's called. .. code-block:: php @@ -34,7 +34,7 @@ Parameters The filter criteria that specifies the documents to update. ``$update`` : array|object - Specifies the field and value combinations to update and any relevant update + The field and value combinations to update and any relevant update operators. ``$update`` uses MongoDB's :manual:`update operators `. You can pass an :manual:`aggregation pipeline ` as this parameter. diff --git a/source/reference/method/MongoDBClientBulkWrite-updateOne.txt b/source/reference/method/MongoDBClientBulkWrite-updateOne.txt index 2de70ed3..88f542bf 100644 --- a/source/reference/method/MongoDBClientBulkWrite-updateOne.txt +++ b/source/reference/method/MongoDBClientBulkWrite-updateOne.txt @@ -17,7 +17,7 @@ Definition Specify an update operation in the bulk write command for the first matching document. This method returns the - :phpclass:`MongoDB\ClientBulkWrite` instance on which its called. + :phpclass:`MongoDB\ClientBulkWrite` instance on which it's called. .. code-block:: php @@ -34,7 +34,7 @@ Parameters The filter criteria that specifies the documents to update. ``$update`` : array|object - Specifies the field and value combinations to update and any relevant update + The field and value combinations to update and any relevant update operators. ``$update`` uses MongoDB's :manual:`update operators `. You can pass an :manual:`aggregation pipeline ` as diff --git a/source/reference/method/MongoDBClientBulkWrite-withCollection.txt b/source/reference/method/MongoDBClientBulkWrite-withCollection.txt index 24823322..0b329491 100644 --- a/source/reference/method/MongoDBClientBulkWrite-withCollection.txt +++ b/source/reference/method/MongoDBClientBulkWrite-withCollection.txt @@ -18,8 +18,7 @@ Definition Return an updated instance of :phpclass:`MongoDB\ClientBulkWrite` from the provided :phpclass:`MongoDB\Collection` instance. This method allows you to add subsequent write operations on a different - collection than that with which the ``ClientBulkWrite`` was created - with. + collection than that with which the ``ClientBulkWrite`` was created. This method does not build a new :php:`BulkWriteCommand ` and does not edit the diff --git a/source/reference/method/MongoDBCollection-bulkWrite.txt b/source/reference/method/MongoDBCollection-bulkWrite.txt index b9367a6f..2f607ea4 100644 --- a/source/reference/method/MongoDBCollection-bulkWrite.txt +++ b/source/reference/method/MongoDBCollection-bulkWrite.txt @@ -104,10 +104,10 @@ Parameters * - ordered - boolean - - If ``true``: when a single write fails, the operation will stop without + - If ``true``: When a single write fails, the operation will stop without performing the remaining writes and throw an exception. - If ``false``: when a single write fails, the operation will continue + If ``false``: When a single write fails, the operation will continue with the remaining writes, if any, and throw an exception. The default is ``true``. diff --git a/source/reference/method/MongoDBCollection-insertMany.txt b/source/reference/method/MongoDBCollection-insertMany.txt index 85875ca5..4e07aa0a 100644 --- a/source/reference/method/MongoDBCollection-insertMany.txt +++ b/source/reference/method/MongoDBCollection-insertMany.txt @@ -64,10 +64,10 @@ Parameters * - ordered - boolean - - If ``true``: when a single write fails, the operation will stop without + - If ``true``: When a single write fails, the operation will stop without performing the remaining writes and throw an exception. - If ``false``: when a single write fails, the operation will continue + If ``false``: When a single write fails, the operation will continue with the remaining writes, if any, and throw an exception. The default is ``true``. diff --git a/source/write/bulk-write.txt b/source/write/bulk-write.txt index 4f713b12..209c4638 100644 --- a/source/write/bulk-write.txt +++ b/source/write/bulk-write.txt @@ -90,7 +90,8 @@ Then, call one or more of the following write methods on the - ``updateMany()`` To select a different namespace for subsequent write operations, call -the ``withCollection()`` method on the ``ClientBulkWrite`` instance: +the ``withCollection()`` method on the ``ClientBulkWrite`` instance, as +shown in the following code: .. code-block:: php :emphasize-lines: 2 @@ -107,10 +108,10 @@ demonstrates how to pass the ``ClientBulkWrite`` object to the Insert Operations ~~~~~~~~~~~~~~~~~ -To specify an insert operation, create an instance of the -``ClientBulkWrite`` class, then call the ``insertOne()`` method. +To specify an insert operation, call the ``insertOne()`` method on your +``ClientBulkWrite`` instance. -The following example specifies insertion of documents into the +The following example specifies the insertion of documents into the ``sample_restaurants.restaurants`` and ``sample_mflix.movies`` collections: @@ -124,12 +125,12 @@ collections: Update Operations ~~~~~~~~~~~~~~~~~ -To specify an update operation on the first matching document, create an -instance of the ``ClientBulkWrite`` class, then call the ``updateOne()`` -method. +To specify an update operation on the first matching document, call the +``updateOne()`` method on your ``ClientBulkWrite`` instance. -The following example specifies an update to a document in the -``sample_restaurants.restaurants`` collection: +The following example specifies a ``$set`` update to the first document +in the ``sample_restaurants.restaurants`` collection that has a ``name`` +value of ``'Dandelion Bakery'``: .. literalinclude:: /includes/write/bulk-write.php :start-after: start-bulk-client-update-one @@ -141,8 +142,9 @@ The following example specifies an update to a document in the To update multiple documents, call the ``updateMany()`` method. The specified operation updates *all documents* that match the query filter. -The following example specifies an update to all matching documents in the -``sample_restaurants.restaurants`` collection: +The following example specifies a ``$set`` update to all matching documents +in the ``sample_restaurants.restaurants`` collection that have a ``name`` +value of ``'Starbucks'``: .. literalinclude:: /includes/write/bulk-write.php :start-after: start-bulk-client-update-many @@ -154,12 +156,12 @@ The following example specifies an update to all matching documents in the Replace Operations ~~~~~~~~~~~~~~~~~~ -To specify an replace operation on the first matching document, create an -instance of the ``ClientBulkWrite`` class, then call the ``replaceOne()`` -method. +To specify an replace operation on the first matching document, call the +``replaceOne()`` method on your ``ClientBulkWrite`` instance. -The following example specifies a replace operation on a document in the -``sample_restaurants.restaurants`` collection: +The following example specifies a replace operation on the first document +in the ``sample_restaurants.restaurants`` collection that has a ``name`` +value of ``'Dandelion Bakery'``: .. literalinclude:: /includes/write/bulk-write.php :start-after: start-bulk-client-replace-one @@ -171,12 +173,12 @@ The following example specifies a replace operation on a document in the Delete Operations ~~~~~~~~~~~~~~~~~ -To specify an delete operation on the first matching document, create an -instance of the ``ClientBulkWrite`` class, then call the ``deleteOne()`` -method. +To specify an delete operation on the first matching document, call the +``deleteOne()`` method on your ``ClientBulkWrite`` instance. -The following example specifies deletion of a document in the -``sample_restaurants.restaurants`` collection: +The following example specifies the deletion of the first document +in the ``sample_restaurants.restaurants`` collection that has a ``borough`` +value of ``'Queens'``: .. literalinclude:: /includes/write/bulk-write.php :start-after: start-bulk-client-delete-one @@ -188,8 +190,9 @@ The following example specifies deletion of a document in the To delete multiple documents, call the ``deleteMany()`` method. The specified operation deletes *all documents* that match the query filter. -The following example specifies deletion of all matching documents in the -``sample_restaurants.restaurants`` collection: +The following example specifies the deletion of all documents +in the ``sample_restaurants.restaurants`` collection that have a ``name`` +value that contains two consecutive ``'p'`` characters: .. literalinclude:: /includes/write/bulk-write.php :start-after: start-bulk-client-delete-many @@ -218,6 +221,7 @@ to perform a bulk write operation on multiple namespaces: :start-after: start-bulk-client :end-before: end-bulk-client :language: php + :emphasize-lines: 30 :dedent: .. output:: @@ -250,7 +254,7 @@ you can set in the array: exist. For more information about schema validation, see :manual:`Schema Validation ` in the {+mdb-server+} manual. - | Defaults to ``false``. + | The default is ``false``. * - ``comment`` - | Attaches a comment to the operation. For more information, see the :manual:`insert command @@ -265,15 +269,15 @@ you can set in the array: {+mdb-server+} manual. * - ``ordered`` - - | If set to ``true``: when a single write fails, the operation stops without - performing the remaining writes and throws an exception. - | If set to ``false``: when a single write fails, the operation continues to - attempt the remaining write operations, if any, then throws an exception. - | Defaults to ``true``. + - | If set to ``true``: When a single write fails, the operation stops without + performing the remaining writes and returns an exception. + | If set to ``false``: When a single write fails, the operation continues to + attempt the remaining write operations, if any, then returns an exception. + | The default is ``true``. * - ``verboseResults`` - | Specifies whether to return verbose results. - | Defaults to ``false``. + | The default is ``false``. The following example creates a ``ClientBulkWrite`` instance and sets the ``ordered`` option to ``false``: @@ -284,13 +288,20 @@ the ``ordered`` option to ``false``: :language: php :dedent: -If the library runs the insert operation first, one document is deleted. -If it runs the delete operation first, no documents are deleted. - -.. note:: +.. note:: Unordered Behavior Unordered bulk operations do not guarantee order of execution. The order can - differ from the way you list them to optimize the runtime. + differ from the way you list them to optimize the runtime. Suppose + you specify the following write operations in an unordered bulk write: + + .. literalinclude:: /includes/write/bulk-write.php + :start-after: start-bulk-client-unordered-behavior + :end-before: end-bulk-client-unordered-behavior + :language: php + :dedent: + + Because the library might run either operation first, the result + can show one deleted document or no deleted documents. You can also pass options when calling the ``bulkWrite()`` method to specify the client session or the write concern to use for the operation. @@ -345,8 +356,8 @@ object. This class contains the following methods: a document with information corresponding to the operation. * - ``isAcknowledged()`` - - | Returns a boolean indicating whether the bulk operation was - acknowledged by the server. + - | Returns a boolean indicating whether the server acknowledged + the bulk operation. .. _php-coll-bulk-write: @@ -427,7 +438,7 @@ describes the options you can set in the array: exist. For more information about schema validation, see :manual:`Schema Validation ` in the {+mdb-server+} manual. - | Defaults to ``false``. + | The default is ``false``. * - ``codec`` - | Sets the codec to use for encoding or decoding documents. Bulk writes @@ -447,11 +458,11 @@ describes the options you can set in the array: {+mdb-server+} manual. * - ``ordered`` - - | If set to ``true``: when a single write fails, the operation stops without - performing the remaining writes and throws an exception. - | If set to ``false``: when a single write fails, the operation continues to - attempt the remaining write operations, if any, then throws an exception. - | Defaults to ``true``. + - | If set to ``true``: When a single write fails, the operation stops without + performing the remaining writes and returns an exception. + | If set to ``false``: When a single write fails, the operation continues to + attempt the remaining write operations, if any, then returns an exception. + | The default is ``true``. * - ``comment`` - | Attaches a comment to the operation. For more information, see the :manual:`insert command @@ -474,7 +485,7 @@ insert and delete operation and sets the ``ordered`` option to If the library runs the insert operation first, one document is deleted. If it runs the delete operation first, no documents are deleted. -.. note:: +.. note:: Unordered Behavior Unordered bulk operations do not guarantee order of execution. The order can differ from the way you list them to optimize the runtime. @@ -524,8 +535,8 @@ object. This class contains the following methods: operations in the bulk write command. * - ``isAcknowledged()`` - - | Returns a boolean indicating whether the bulk operation was - acknowledged by the server. + - | Returns a boolean indicating whether the server acknowledged + the bulk operation. Additional Information ---------------------- diff --git a/source/write/replace.txt b/source/write/replace.txt index 5c3ba370..60f60601 100644 --- a/source/write/replace.txt +++ b/source/write/replace.txt @@ -96,7 +96,8 @@ methods: performed an upsert. * - ``isAcknowledged()`` - - | Returns a boolean indicating whether the write operation was acknowledged. + - | Returns a boolean indicating whether the server acknowledged + the write operation. Example ~~~~~~~ diff --git a/source/write/update.txt b/source/write/update.txt index b6e22d02..d70b6f5a 100644 --- a/source/write/update.txt +++ b/source/write/update.txt @@ -190,7 +190,8 @@ member functions: count. * - ``isAcknowledged()`` - - | Returns a boolean indicating whether the write operation was acknowledged. + - | Returns a boolean indicating whether the server acknowledged + the write operation. * - ``getUpsertedCount()`` - | Returns the number of document that were upserted into the database. From 7166329d91e91e468db34aba4562cf4d8e6e3bea Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 21 May 2025 15:48:34 -0400 Subject: [PATCH 12/12] returns -> throws --- .../MongoDBClientBulkWrite-createWithCollection.txt | 4 ++-- source/write/bulk-write.txt | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/source/reference/method/MongoDBClientBulkWrite-createWithCollection.txt b/source/reference/method/MongoDBClientBulkWrite-createWithCollection.txt index 478c70a8..44928fbb 100644 --- a/source/reference/method/MongoDBClientBulkWrite-createWithCollection.txt +++ b/source/reference/method/MongoDBClientBulkWrite-createWithCollection.txt @@ -64,10 +64,10 @@ Parameters * - ordered - boolean - If ``true``: When a single write fails, the operation stops without - performing the remaining writes and returns an exception. + performing the remaining writes and throws an exception. If ``false``: When a single write fails, the operation continues - with the remaining writes, if any, and returns an exception. + with the remaining writes, if any, and throws an exception. The default is ``true``. diff --git a/source/write/bulk-write.txt b/source/write/bulk-write.txt index 209c4638..9b6d40b4 100644 --- a/source/write/bulk-write.txt +++ b/source/write/bulk-write.txt @@ -270,9 +270,9 @@ you can set in the array: * - ``ordered`` - | If set to ``true``: When a single write fails, the operation stops without - performing the remaining writes and returns an exception. + performing the remaining writes and throws an exception. | If set to ``false``: When a single write fails, the operation continues to - attempt the remaining write operations, if any, then returns an exception. + attempt the remaining write operations, if any, then throws an exception. | The default is ``true``. * - ``verboseResults`` @@ -459,9 +459,9 @@ describes the options you can set in the array: * - ``ordered`` - | If set to ``true``: When a single write fails, the operation stops without - performing the remaining writes and returns an exception. + performing the remaining writes and throws an exception. | If set to ``false``: When a single write fails, the operation continues to - attempt the remaining write operations, if any, then returns an exception. + attempt the remaining write operations, if any, then throws an exception. | The default is ``true``. * - ``comment``