diff --git a/language-snippets.ent b/language-snippets.ent index c464faef565e..16441f8ed6fc 100644 --- a/language-snippets.ent +++ b/language-snippets.ent @@ -3431,6 +3431,16 @@ local: { '> + + bulk (MongoDB\Driver\BulkWriteCommand) + + + The write(s) to execute. + + + +'> command (MongoDB\Driver\Command) @@ -3645,9 +3655,11 @@ local: { '> Returns MongoDB\Driver\Cursor on success.'> Returns MongoDB\Driver\WriteResult on success.'> +Returns MongoDB\Driver\BulkWriteCommandResult on success.'> Throws MongoDB\Driver\Exception\InvalidArgumentException if the "session" option is used with an associated transaction in combination with a "readConcern" or "writeConcern" option.'> Throws MongoDB\Driver\Exception\InvalidArgumentException if the "session" option is used in combination with an unacknowledged write concern.'> +Throws MongoDB\Driver\Exception\BulkWriteCommandException on any write failure (e.g. command failure, write or write concern error)'> Throws MongoDB\Driver\Exception\BulkWriteException on any write failure (e.g. write error, failure to apply a write concern)'> Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.'> Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.'> diff --git a/reference/mongodb/exceptions.xml b/reference/mongodb/exceptions.xml index a43cee4f64b1..a46847f1f283 100644 --- a/reference/mongodb/exceptions.xml +++ b/reference/mongodb/exceptions.xml @@ -7,6 +7,7 @@ &reference.mongodb.mongodb.driver.exception.authenticationexception; &reference.mongodb.mongodb.driver.exception.bulkwriteexception; + &reference.mongodb.mongodb.driver.exception.bulkwritecommandexception; &reference.mongodb.mongodb.driver.exception.commandexception; &reference.mongodb.mongodb.driver.exception.connectionexception; &reference.mongodb.mongodb.driver.exception.connectiontimeoutexception; @@ -51,6 +52,7 @@ MongoDB\Driver\Exception\ServerException + MongoDB\Driver\Exception\BulkWriteCommandException MongoDB\Driver\Exception\CommandException MongoDB\Driver\Exception\ExecutionTimeoutException diff --git a/reference/mongodb/mongodb.xml b/reference/mongodb/mongodb.xml index 01a150305681..7aeae83349e0 100644 --- a/reference/mongodb/mongodb.xml +++ b/reference/mongodb/mongodb.xml @@ -10,6 +10,7 @@ &reference.mongodb.mongodb.driver.command; &reference.mongodb.mongodb.driver.query; &reference.mongodb.mongodb.driver.bulkwrite; + &reference.mongodb.mongodb.driver.bulkwritecommand; &reference.mongodb.mongodb.driver.session; &reference.mongodb.mongodb.driver.clientencryption; &reference.mongodb.mongodb.driver.serverapi; @@ -29,4 +30,5 @@ &reference.mongodb.mongodb.driver.writeconcernerror; &reference.mongodb.mongodb.driver.writeerror; &reference.mongodb.mongodb.driver.writeresult; + &reference.mongodb.mongodb.driver.bulkwritecommandresult; diff --git a/reference/mongodb/mongodb/driver/bulkwritecommand.xml b/reference/mongodb/mongodb/driver/bulkwritecommand.xml new file mode 100644 index 000000000000..6190950932a7 --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommand.xml @@ -0,0 +1,202 @@ + + + + + + The MongoDB\Driver\BulkWriteCommand class + MongoDB\Driver\BulkWriteCommand + + + + +
+ &reftitle.intro; + + MongoDB\Driver\BulkWriteCommand collects one or more + write operations that should be sent to the server using the + bulkWrite + command introduced in MongoDB 8.0. After adding any number of insert, + update, and delete operations, the command may be executed via + MongoDB\Driver\Manager::executeBulkWriteCommand. + + + Unlike MongoDB\Driver\BulkWrite, where all write + operations must target the same collection, each write operation within + MongoDB\Driver\BulkWriteCommand may target a + different collection. + + + Write operations may either be ordered (default) or unordered. Ordered write + operations are sent to the server, in the order provided, for serial + execution. If a write fails, any remaining operations will be aborted. + Unordered operations are sent to the server in an arbitrary order + where they may be executed in parallel. Any errors that occur are reported + after all operations have been attempted. + +
+ + +
+ &reftitle.classsynopsis; + + + + MongoDB\Driver\BulkWriteCommand + + + + final + + MongoDB\Driver\BulkWriteCommand + + + + Countable + + + + + &Methods; + + + + +
+ +
+ &reftitle.examples; + + + Mixed write operations + + Mixed write operations (i.e. inserts, updates, and deletes) will be sent + to the server using a single + bulkWrite + command. + + +deleteMany('db.coll_one', []); +$bulk->deleteMany('db.coll_two', []); + +// Insert documents into two collections +$bulk->insertOne('db.coll_one', ['_id' => 1]); +$bulk->insertOne('db.coll_two', ['_id' => 2]); +$bulk->insertOne('db.coll_two', ['_id' => 3]); + +// Update a document in "coll_one" +$bulk->updateOne('db.coll_one', ['_id' => 1], ['$set' => ['x' => 1]]); + +$result = $manager->executeBulkWriteCommand($bulk); + +printf("Inserted %d document(s)\n", $result->getInsertedCount()); +printf("Updated %d document(s)\n", $result->getModifiedCount()); + +?> +]]> + + &example.outputs; + + + + + + Ordered write operations causing an error + +deleteMany('db.coll', []); +$bulk->insertOne('db.coll', ['_id' => 1]); +$bulk->insertOne('db.coll', ['_id' => 2]); +$bulk->insertOne('db.coll', ['_id' => 1]); +$bulk->insertOne('db.coll', ['_id' => 3]); + +try { + $result = $manager->executeBulkWriteCommand($bulk); +} catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) { + $result = $e->getPartialResult(); + + var_dump($e->getWriteErrors()); +} + +printf("Inserted %d document(s)\n", $result->getInsertedCount()); + +?> +]]> + + &example.outputs.similar; + + + object(MongoDB\Driver\WriteError)#5 (4) { + ["message"]=> + string(78) "E11000 duplicate key error collection: db.coll index: _id_ dup key: { _id: 1 }" + ["code"]=> + int(11000) + ["index"]=> + int(3) + ["info"]=> + object(stdClass)#6 (0) { + } + } +} +Inserted 2 document(s) +]]> + + +
+ +
+ &reftitle.seealso; + + MongoDB\Driver\Manager::executeBulkWriteCommand + MongoDB\Driver\BulkWriteCommandResult + MongoDB\Driver\Exception\BulkWriteCommandException + MongoDB\Driver\WriteConcern + MongoDB\Driver\WriteConcernError + MongoDB\Driver\WriteError + +
+ + + + &reference.mongodb.mongodb.driver.entities.bulkwritecommand; + + + + diff --git a/reference/mongodb/mongodb/driver/bulkwritecommand/construct.xml b/reference/mongodb/mongodb/driver/bulkwritecommand/construct.xml new file mode 100644 index 000000000000..d5daf49b4286 --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommand/construct.xml @@ -0,0 +1,184 @@ + + + + + + MongoDB\Driver\BulkWriteCommand::__construct + Create a new BulkWriteCommand + + + + &reftitle.description; + + public MongoDB\Driver\BulkWriteCommand::__construct + arraynulloptions&null; + + + Constructs a new MongoDB\Driver\BulkWriteCommand, + which may be used to perform many insert, update, and delete operations on + multiple collections in a single request using the + bulkWrite + command introduced in MongoDB 8.0. This differs from + MongoDB\Driver\BulkWrite, which is supported by all + server versions but limited to a single collection. + + + After all write operations have been added, this object may be executed with + MongoDB\Driver\Manager::executeBulkWriteCommand. + + + + + &reftitle.parameters; + + + options (array) + + + + options + + + + Option + Type + Description + Default + + + + + bypassDocumentValidation + bool + + + If &true;, allows insert and update operations to circumvent + document level validation. + + + &false; + + + comment + mixed + + + An arbitrary comment to help trace the operation through the + database profiler, currentOp output, and logs. + + + + &mongodb.option.let; + + ordered + bool + + + Whether the operations in this bulk write should be executed in + the order in which they were specified. If &false;, writes will + continue to be executed if an individual write fails. If &true;, + writes will stop executing if an individual write fails. + + + &true; + + + verboseResults + bool + + + Whether detailed results for each successful operation should be + included in the returned + MongoDB\Driver\BulkWriteCommandResult. + + + &false; + + + +
+ + + + + + + + &reftitle.errors; + + &mongodb.throws.argumentparsing; + + + + + &reftitle.examples; + + <function>MongoDB\Driver\BulkWriteCommand::__construct</function> example + +deleteMany('db.coll_one', []); +$bulk->deleteMany('db.coll_two', []); + +// Insert documents into two collections +$bulk->insertOne('db.coll_one', ['_id' => 1]); +$bulk->insertOne('db.coll_two', ['_id' => 2]); +$bulk->insertOne('db.coll_two', ['_id' => 3]); + +// Update a document in "coll_one" +$bulk->updateOne('db.coll_one', ['_id' => 1], ['$set' => ['x' => 1]]); + +$result = $manager->executeBulkWriteCommand($bulk); + +printf("Inserted %d document(s)\n", $result->getInsertedCount()); +printf("Updated %d document(s)\n", $result->getModifiedCount()); + +?> +]]> + + &example.outputs; + + + + + + + + &reftitle.seealso; + + MongoDB\Driver\Manager::executeBulkWriteCommand + MongoDB\Driver\BulkWriteCommandResult + + + + + + diff --git a/reference/mongodb/mongodb/driver/bulkwritecommand/count.xml b/reference/mongodb/mongodb/driver/bulkwritecommand/count.xml new file mode 100644 index 000000000000..c5c40e24f761 --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommand/count.xml @@ -0,0 +1,92 @@ + + + + + + MongoDB\Driver\BulkWriteCommand::count + Count number of write operations in the BulkWriteCommand + + + + &reftitle.description; + + public intMongoDB\Driver\BulkWriteCommand::count + + + + Returns the number of write operations added to the + MongoDB\Driver\BulkWriteCommand object. + + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns number of write operations added to the + MongoDB\Driver\BulkWriteCommand object. + + + + + &reftitle.errors; + + &mongodb.throws.argumentparsing; + + + + + &reftitle.examples; + + <function>MongoDB\Driver\BulkWriteCommand::count</function> example + +insertOne('db.coll', ['_id' => 1, 'x' => 1]); +$bulk->insertOne('db.coll', ['_id' => 2, 'x' => 2]); +$bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['x' => 1]]); +$bulk->deleteMany('db.coll', ['x' => 1]); + +var_dump(count($bulk)); + +?> +]]> + + &example.outputs; + + + + + + + + + diff --git a/reference/mongodb/mongodb/driver/bulkwritecommand/deletemany.xml b/reference/mongodb/mongodb/driver/bulkwritecommand/deletemany.xml new file mode 100644 index 000000000000..f6c6510eea8a --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommand/deletemany.xml @@ -0,0 +1,133 @@ + + + + + + MongoDB\Driver\BulkWriteCommand::deleteMany + Add a deleteMany operation + + + + &reftitle.description; + + public voidMongoDB\Driver\BulkWriteCommand::deleteMany + stringnamespace + arrayobjectfilter + arraynulloptions&null; + + + Add a deleteMany operation to the + MongoDB\Driver\BulkWriteCommand. All documents + matching filter in the collection identified by + namespace will be deleted. + + + + + &reftitle.parameters; + + &mongodb.parameter.namespace; + &mongodb.parameter.filter; + + options + + + + options + + + + Option + Type + Description + Default + + + + &mongodb.option.collation; + + hint + stringarrayobject + + + Index specification. Specify either the index name as a string or + the index key pattern. If specified, then the query system will only + consider plans using the hinted index. + + + + + +
+ + + + + + + + &reftitle.returnvalues; + + &return.void; + + + + + &reftitle.errors; + + &mongodb.throws.argumentparsing; + + + + + &reftitle.examples; + + <function>MongoDB\Driver\BulkWriteCommand::deleteMany</function> example + +deleteMany('db.coll', ['x' => ['$gt' => 1]]); + +$result = $manager->executeBulkWriteCommand($bulk); + +?> +]]> + + + + + + &reftitle.seealso; + + MongoDB\Driver\BulkWriteCommand::deleteOne + MongoDB\Driver\Manager::executeBulkWriteCommand + MongoDB\Driver\BulkWriteCommandResult + + + + + + diff --git a/reference/mongodb/mongodb/driver/bulkwritecommand/deleteone.xml b/reference/mongodb/mongodb/driver/bulkwritecommand/deleteone.xml new file mode 100644 index 000000000000..15f875218ffa --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommand/deleteone.xml @@ -0,0 +1,133 @@ + + + + + + MongoDB\Driver\BulkWriteCommand::deleteOne + Add a deleteOne operation + + + + &reftitle.description; + + public voidMongoDB\Driver\BulkWriteCommand::deleteOne + stringnamespace + arrayobjectfilter + arraynulloptions&null; + + + Add a deleteOne operation to the + MongoDB\Driver\BulkWriteCommand. The first document + matching filter in the collection identified by + namespace will be deleted. + + + + + &reftitle.parameters; + + &mongodb.parameter.namespace; + &mongodb.parameter.filter; + + options + + + + options + + + + Option + Type + Description + Default + + + + &mongodb.option.collation; + + hint + stringarrayobject + + + Index specification. Specify either the index name as a string or + the index key pattern. If specified, then the query system will only + consider plans using the hinted index. + + + + + +
+ + + + + + + + &reftitle.returnvalues; + + &return.void; + + + + + &reftitle.errors; + + &mongodb.throws.argumentparsing; + + + + + &reftitle.examples; + + <function>MongoDB\Driver\BulkWriteCommand::deleteOne</function> example + +deleteOne('db.coll', ['x' => 1]); + +$result = $manager->executeBulkWriteCommand($bulk); + +?> +]]> + + + + + + &reftitle.seealso; + + MongoDB\Driver\BulkWriteCommand::deleteMany + MongoDB\Driver\Manager::executeBulkWriteCommand + MongoDB\Driver\BulkWriteCommandResult + + + + + + diff --git a/reference/mongodb/mongodb/driver/bulkwritecommand/insertone.xml b/reference/mongodb/mongodb/driver/bulkwritecommand/insertone.xml new file mode 100644 index 000000000000..453bfbdb4b68 --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommand/insertone.xml @@ -0,0 +1,131 @@ + + + + + + MongoDB\Driver\BulkWriteCommand::insertOne + Add an insertOne operation + + + + &reftitle.description; + + public mixedMongoDB\Driver\BulkWriteCommand::insertOne + stringnamespace + arrayobjectdocument + + + Add an insertOne operation to the + MongoDB\Driver\BulkWriteCommand. The document will + be inserted into the collection identified by + namespace. + + + + + &reftitle.parameters; + + &mongodb.parameter.namespace; + + document (arrayobject) + + + A document to insert. + + + + + + + + &reftitle.returnvalues; + + Returns the _id of the inserted document. If the + document did not have an _id, the + MongoDB\BSON\ObjectId generated for the insert will + be returned. + + + + + &reftitle.errors; + + &mongodb.throws.argumentparsing; + + + + + &reftitle.examples; + + <function>MongoDB\Driver\BulkWriteCommand::insertOne</function> example + + 1]; +$doc2 = ['_id' => 'custom-id', 'x' => 2]; +$doc3 = ['_id' => new MongoDB\BSON\ObjectId('0123456789abcdef01234567'), 'x' => 3]; + +$id1 = $bulk->insertOne('db.coll', $doc1); +$id2 = $bulk->insertOne('db.coll', $doc2); +$id3 = $bulk->insertOne('db.coll', $doc3); + +var_dump($id1, $id2, $id3); + +$result = $manager->executeBulkWriteCommand($bulk); + +?> +]]> + + &example.outputs.similar; + + + string(24) "67f58058d1a0aa2fd80d55d0" +} +string(9) "custom-id" +object(MongoDB\BSON\ObjectId)#4 (1) { + ["oid"]=> + string(24) "0123456789abcdef01234567" +} +]]> + + + + + + &reftitle.seealso; + + MongoDB\Driver\Manager::executeBulkWriteCommand + MongoDB\Driver\BulkWriteCommandResult + MongoDB\BSON\ObjectId + + + + + + diff --git a/reference/mongodb/mongodb/driver/bulkwritecommand/replaceone.xml b/reference/mongodb/mongodb/driver/bulkwritecommand/replaceone.xml new file mode 100644 index 000000000000..139e6decb6e6 --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommand/replaceone.xml @@ -0,0 +1,165 @@ + + + + + + MongoDB\Driver\BulkWriteCommand::replaceOne + Add a replaceOne operation + + + + &reftitle.description; + + public voidMongoDB\Driver\BulkWriteCommand::replaceOne + stringnamespace + arrayobjectfilter + arrayobjectreplacement + arraynulloptions&null; + + + Add a replaceOne operation to the + MongoDB\Driver\BulkWriteCommand. The first document + matching filter in the collection identified by + namespace will be replaced. + + + + + + &reftitle.parameters; + + &mongodb.parameter.namespace; + &mongodb.parameter.filter; + + replacement (arrayobject) + + + A replacement document. + + + + + options + + + + options + + + + Option + Type + Description + Default + + + + &mongodb.option.collation; + + hint + stringarrayobject + + + Index specification. Specify either the index name as a string or + the index key pattern. If specified, then the query system will only + consider plans using the hinted index. + + + + + sort + arrayobject + + + Specify which document the operation replaces if the query matches + multiple documents. The first document matched by the sort order + will be replaced. + + + + + upsert + bool + + If filter does not match an existing document, + insert a single document. The document will be + created from replacement. + + &false; + + + +
+ + + + + + + + &reftitle.returnvalues; + + &return.void; + + + + + &reftitle.errors; + + &mongodb.throws.argumentparsing; + + + + + &reftitle.examples; + + <function>MongoDB\Driver\BulkWriteCommand::replaceOne</function> example + +replaceOne('db.coll', ['x' => 1], ['x' => 1, 'y' = 2]); + +$result = $manager->executeBulkWriteCommand($bulk); + +?> +]]> + + + + + + &reftitle.seealso; + + MongoDB\Driver\BulkWriteCommand::updateOne + MongoDB\Driver\BulkWriteCommand::updateMany + MongoDB\Driver\Manager::executeBulkWriteCommand + MongoDB\Driver\BulkWriteCommandResult + + + + + + diff --git a/reference/mongodb/mongodb/driver/bulkwritecommand/updatemany.xml b/reference/mongodb/mongodb/driver/bulkwritecommand/updatemany.xml new file mode 100644 index 000000000000..b4f87fa13c75 --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommand/updatemany.xml @@ -0,0 +1,169 @@ + + + + + + MongoDB\Driver\BulkWriteCommand::updateMany + Add an updateMany operation + + + + &reftitle.description; + + public voidMongoDB\Driver\BulkWriteCommand::updateMany + stringnamespace + arrayobjectfilter + arrayobjectupdate + arraynulloptions&null; + + + Add an updateMany operation to the + MongoDB\Driver\BulkWriteCommand. All documents + matching filter in the collection identified by + namespace will be updated. + + + + + + &reftitle.parameters; + + &mongodb.parameter.namespace; + &mongodb.parameter.filter; + + update (arrayobject) + + + A document containing either update operators (e.g. + $set) or an + aggregation pipeline. + + + + + options + + + + options + + + + Option + Type + Description + Default + + + + + arrayFilters + array + + + An array of filter documents that determines which array elements to + modify for an update operation on an array field. See + Specify arrayFilters for Array Update Operations + in the MongoDB manual for more information. + + + + &mongodb.option.collation; + + hint + stringarrayobject + + + Index specification. Specify either the index name as a string or + the index key pattern. If specified, then the query system will only + consider plans using the hinted index. + + + + + upsert + bool + + If filter does not match an existing document, + insert a single document. The document will be + created by applying operators in update to any + field values in filter. + + &false; + + + +
+ + + + + + + + &reftitle.returnvalues; + + &return.void; + + + + + &reftitle.errors; + + &mongodb.throws.argumentparsing; + + + + + &reftitle.examples; + + <function>MongoDB\Driver\BulkWriteCommand::updateMany</function> example + +updateMany('db.coll', ['x' => ['$gt' => 1]], ['$set' => ['y' => 2]]); + +$result = $manager->executeBulkWriteCommand($bulk); + +?> +]]> + + + + + + &reftitle.seealso; + + MongoDB\Driver\BulkWriteCommand::replaceOne + MongoDB\Driver\BulkWriteCommand::updateMany + MongoDB\Driver\Manager::executeBulkWriteCommand + MongoDB\Driver\BulkWriteCommandResult + + + + + + diff --git a/reference/mongodb/mongodb/driver/bulkwritecommand/updateone.xml b/reference/mongodb/mongodb/driver/bulkwritecommand/updateone.xml new file mode 100644 index 000000000000..efa7b9afacdc --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommand/updateone.xml @@ -0,0 +1,180 @@ + + + + + + MongoDB\Driver\BulkWriteCommand::updateOne + Add an updateOne operation + + + + &reftitle.description; + + public voidMongoDB\Driver\BulkWriteCommand::updateOne + stringnamespace + arrayobjectfilter + arrayobjectupdate + arraynulloptions&null; + + + Add an updateOne operation to the + MongoDB\Driver\BulkWriteCommand. The first document + matching filter in the collection identified by + namespace will be updated. + + + + + + &reftitle.parameters; + + &mongodb.parameter.namespace; + &mongodb.parameter.filter; + + update (arrayobject) + + + A document containing either update operators (e.g. + $set) or an + aggregation pipeline. + + + + + options + + + + options + + + + Option + Type + Description + Default + + + + + arrayFilters + array + + + An array of filter documents that determines which array elements to + modify for an update operation on an array field. See + Specify arrayFilters for Array Update Operations + in the MongoDB manual for more information. + + + + &mongodb.option.collation; + + hint + stringarrayobject + + + Index specification. Specify either the index name as a string or + the index key pattern. If specified, then the query system will only + consider plans using the hinted index. + + + + + sort + arrayobject + + + Specify which document the operation updates if the query matches + multiple documents. The first document matched by the sort order + will be updated. + + + + + upsert + bool + + If filter does not match an existing document, + insert a single document. The document will be + created by applying operators in update to any + field values in filter. + + &false; + + + +
+ + + + + + + + &reftitle.returnvalues; + + &return.void; + + + + + &reftitle.errors; + + &mongodb.throws.argumentparsing; + + + + + &reftitle.examples; + + <function>MongoDB\Driver\BulkWriteCommand::updateOne</function> example + +updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 2]]); + +$result = $manager->executeBulkWriteCommand($bulk); + +?> +]]> + + + + + + &reftitle.seealso; + + MongoDB\Driver\BulkWriteCommand::replaceOne + MongoDB\Driver\BulkWriteCommand::updateMany + MongoDB\Driver\Manager::executeBulkWriteCommand + MongoDB\Driver\BulkWriteCommandResult + + + + + + diff --git a/reference/mongodb/mongodb/driver/bulkwritecommandresult.xml b/reference/mongodb/mongodb/driver/bulkwritecommandresult.xml new file mode 100644 index 000000000000..6f4998e8d47b --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommandresult.xml @@ -0,0 +1,71 @@ + + + + + + The MongoDB\Driver\BulkWriteCommandResult class + MongoDB\Driver\BulkWriteCommandResult + + + + +
+ &reftitle.intro; + + The MongoDB\Driver\BulkWriteCommandResult class + encapsulates information about an executed + MongoDB\Driver\BulkWriteCommand and is returned by + MongoDB\Driver\Manager::executeBulkWriteCommand. + +
+ + +
+ &reftitle.classsynopsis; + + + + MongoDB\Driver\BulkWriteCommandResult + + + + final + + MongoDB\Driver\BulkWriteCommandResult + + + + + &Methods; + + + + +
+ + + + &reference.mongodb.mongodb.driver.entities.bulkwritecommandresult; + + + + diff --git a/reference/mongodb/mongodb/driver/bulkwritecommandresult/getdeletedcount.xml b/reference/mongodb/mongodb/driver/bulkwritecommandresult/getdeletedcount.xml new file mode 100644 index 000000000000..0c8a17ea1e1e --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommandresult/getdeletedcount.xml @@ -0,0 +1,102 @@ + + + + + + MongoDB\Driver\BulkWriteCommandResult::getDeletedCount + Returns the number of documents deleted + + + + &reftitle.description; + + final public intMongoDB\Driver\BulkWriteCommandResult::getDeletedCount + + + + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns the total number of documents deleted by all operations. + + + + + &reftitle.errors; + + &mongodb.throws.argumentparsing; + &mongodb.throws.unacknowledged; + + + + + &reftitle.examples; + + <function>MongoDB\Driver\BulkWriteCommandResult::getDeletedCount</function> example + +insertOne('db.coll', ['x' => 1]); +$bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]); +$bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]); +$bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]); +$bulk->deleteMany('db.coll', []); + +$result = $manager->executeBulkWriteCommand($bulk); + +var_dump($result->getDeletedCount()); + +?> +]]> + + &example.outputs; + + + + + + + + &reftitle.seealso; + + MongoDB\Driver\BulkWriteCommandResult::getDeleteResults + MongoDB\Driver\BulkWriteCommandResult::isAcknowledged + + + + + + diff --git a/reference/mongodb/mongodb/driver/bulkwritecommandresult/getdeleteresults.xml b/reference/mongodb/mongodb/driver/bulkwritecommandresult/getdeleteresults.xml new file mode 100644 index 000000000000..2667f2b56aef --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommandresult/getdeleteresults.xml @@ -0,0 +1,114 @@ + + + + + + MongoDB\Driver\BulkWriteCommandResult::getDeleteResults + Returns verbose results for successful deletes + + + + &reftitle.description; + + final public MongoDB\BSON\DocumentnullMongoDB\Driver\BulkWriteCommandResult::getDeleteResults + + + + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns a document containing the result of each successful delete + operation, or &null; if verbose results were not requested. The document + keys will correspond to the index of the write operation from + MongoDB\Driver\BulkWriteCommand. + + + + + &reftitle.errors; + + &mongodb.throws.argumentparsing; + &mongodb.throws.unacknowledged; + + + + + &reftitle.examples; + + <function>MongoDB\Driver\BulkWriteCommandResult::getDeleteResults</function> example + + true]); +$bulk->insertOne('db.coll', ['x' => 1]); +$bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]); +$bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]); +$bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]); +$bulk->deleteMany('db.coll', []); + +$result = $manager->executeBulkWriteCommand($bulk); + +var_dump($result->getDeleteResults()->toPHP()); + +?> +]]> + + &example.outputs.similar; + + + object(stdClass)#6 (1) { + ["deletedCount"]=> + object(MongoDB\BSON\Int64)#5 (1) { + ["integer"]=> + string(1) "3" + } + } +} +]]> + + + + + + &reftitle.seealso; + + MongoDB\Driver\BulkWriteCommandResult::getDeletedCount + MongoDB\Driver\BulkWriteCommandResult::isAcknowledged + + + + + + diff --git a/reference/mongodb/mongodb/driver/bulkwritecommandresult/getinsertedcount.xml b/reference/mongodb/mongodb/driver/bulkwritecommandresult/getinsertedcount.xml new file mode 100644 index 000000000000..0a858440597d --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommandresult/getinsertedcount.xml @@ -0,0 +1,103 @@ + + + + + + MongoDB\Driver\BulkWriteCommandResult::getInsertedCount + Returns the number of documents inserted + + + + &reftitle.description; + + final public intMongoDB\Driver\BulkWriteCommandResult::getInsertedCount + + + + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns the total number of documents inserted (excluding upserts) by all + operations. + + + + + &reftitle.errors; + + &mongodb.throws.argumentparsing; + &mongodb.throws.unacknowledged; + + + + + &reftitle.examples; + + <function>MongoDB\Driver\BulkWriteCommandResult::getInsertedCount</function> example + +insertOne('db.coll', ['x' => 1]); +$bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]); +$bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]); +$bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]); +$bulk->deleteMany('db.coll', []); + +$result = $manager->executeBulkWriteCommand($bulk); + +var_dump($result->getInsertedCount()); + +?> +]]> + + &example.outputs; + + + + + + + + &reftitle.seealso; + + MongoDB\Driver\BulkWriteCommandResult::getInsertResults + MongoDB\Driver\BulkWriteCommandResult::isAcknowledged + + + + + + diff --git a/reference/mongodb/mongodb/driver/bulkwritecommandresult/getinsertresults.xml b/reference/mongodb/mongodb/driver/bulkwritecommandresult/getinsertresults.xml new file mode 100644 index 000000000000..63feaa022866 --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommandresult/getinsertresults.xml @@ -0,0 +1,128 @@ + + + + + + MongoDB\Driver\BulkWriteCommandResult::getInsertResults + Returns verbose results for successful inserts + + + + &reftitle.description; + + final public MongoDB\BSON\DocumentnullMongoDB\Driver\BulkWriteCommandResult::getInsertResults + + + + Since _id fields for inserted documents are generated by + the extension, the value of insertedId in each result + will match the return value of + MongoDB\Driver\BulkWriteCommand::insertOne for + the corresponding insert operation. + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns a document containing the result of each successful insert + operation, or &null; if verbose results were not requested. The document + keys will correspond to the index of the write operation from + MongoDB\Driver\BulkWriteCommand. + + + + + &reftitle.errors; + + &mongodb.throws.argumentparsing; + &mongodb.throws.unacknowledged; + + + + + &reftitle.examples; + + <function>MongoDB\Driver\BulkWriteCommandResult::getInsertResults</function> example + + true]); + +$generatedId = $bulk->insertOne('db.coll', ['x' => 1]); + +$bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]); +$bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]); +$bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]); +$bulk->deleteMany('db.coll', []); + +$result = $manager->executeBulkWriteCommand($bulk); + +var_dump($generatedId); + +var_dump($result->getInsertResults()->toPHP()); + +?> +]]> + + &example.outputs.similar; + + + string(24) "67f7ee69783dcce702097b41" +} +object(stdClass)#8 (1) { + ["0"]=> + object(stdClass)#7 (1) { + ["insertedId"]=> + object(MongoDB\BSON\ObjectId)#6 (1) { + ["oid"]=> + string(24) "67f7ee69783dcce702097b41" + } + } +} +]]> + + + + + + &reftitle.seealso; + + MongoDB\Driver\BulkWriteCommandResult::getInsertedCount + MongoDB\Driver\BulkWriteCommandResult::isAcknowledged + MongoDB\Driver\BulkWriteCommand::insertOne + + + + + + diff --git a/reference/mongodb/mongodb/driver/bulkwritecommandresult/getmatchedcount.xml b/reference/mongodb/mongodb/driver/bulkwritecommandresult/getmatchedcount.xml new file mode 100644 index 000000000000..036a1a6fe39a --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommandresult/getmatchedcount.xml @@ -0,0 +1,107 @@ + + + + + + MongoDB\Driver\BulkWriteCommandResult::getMatchedCount + Returns the number of documents selected for update + + + + &reftitle.description; + + final public intMongoDB\Driver\BulkWriteCommandResult::getMatchedCount + + + + If the update operation results in no change to the document (e.g. setting + the value of a field to its current value), the matched count may be greater + than the value returned by + MongoDB\Driver\BulkWriteCommandResult::getModifiedCount. + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns the total number of documents selected for update by all operations. + + + + + &reftitle.errors; + + &mongodb.throws.argumentparsing; + &mongodb.throws.unacknowledged; + + + + + &reftitle.examples; + + <function>MongoDB\Driver\BulkWriteCommandResult::getMatchedCount</function> example + +insertOne('db.coll', ['x' => 1]); +$bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]); +$bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]); +$bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]); +$bulk->deleteMany('db.coll', []); + +$result = $manager->executeBulkWriteCommand($bulk); + +var_dump($result->getMatchedCount()); + +?> +]]> + + &example.outputs; + + + + + + + + &reftitle.seealso; + + MongoDB\Driver\BulkWriteCommandResult::getModifiedCount + MongoDB\Driver\BulkWriteCommandResult::getUpdateResults + MongoDB\Driver\BulkWriteCommandResult::isAcknowledged + + + + + + diff --git a/reference/mongodb/mongodb/driver/bulkwritecommandresult/getmodifiedcount.xml b/reference/mongodb/mongodb/driver/bulkwritecommandresult/getmodifiedcount.xml new file mode 100644 index 000000000000..eb19dc13a1a2 --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommandresult/getmodifiedcount.xml @@ -0,0 +1,107 @@ + + + + + + MongoDB\Driver\BulkWriteCommandResult::getModifiedCount + Returns the number of existing documents updated + + + + &reftitle.description; + + final public intMongoDB\Driver\BulkWriteCommandResult::getModifiedCount + + + + If the update operation results in no change to the document (e.g. setting + the value of a field to its current value), the modified count may be less + than the value returned by + MongoDB\Driver\BulkWriteCommandResult::getMatchedCount. + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns the total number of existing documents updated by all operations. + + + + + &reftitle.errors; + + &mongodb.throws.argumentparsing; + &mongodb.throws.unacknowledged; + + + + + &reftitle.examples; + + <function>MongoDB\Driver\BulkWriteCommandResult::getModifiedCount</function> example + +insertOne('db.coll', ['x' => 1]); +$bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]); +$bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]); +$bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]); +$bulk->deleteMany('db.coll', []); + +$result = $manager->executeBulkWriteCommand($bulk); + +var_dump($result->getModifiedCount()); + +?> +]]> + + &example.outputs; + + + + + + + + &reftitle.seealso; + + MongoDB\Driver\BulkWriteCommandResult::getMatchedCount + MongoDB\Driver\BulkWriteCommandResult::getUpdateResults + MongoDB\Driver\BulkWriteCommandResult::isAcknowledged + + + + + + diff --git a/reference/mongodb/mongodb/driver/bulkwritecommandresult/getupdateresults.xml b/reference/mongodb/mongodb/driver/bulkwritecommandresult/getupdateresults.xml new file mode 100644 index 000000000000..9f4d2de1261b --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommandresult/getupdateresults.xml @@ -0,0 +1,157 @@ + + + + + + MongoDB\Driver\BulkWriteCommandResult::getUpdateResults + Returns verbose results for successful updates + + + + &reftitle.description; + + final public MongoDB\BSON\DocumentnullMongoDB\Driver\BulkWriteCommandResult::getUpdateResults + + + + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns a document containing the result of each successful update + operation, or &null; if verbose results were not requested. The document + keys will correspond to the index of the write operation from + MongoDB\Driver\BulkWriteCommand. + + + + + &reftitle.errors; + + &mongodb.throws.argumentparsing; + &mongodb.throws.unacknowledged; + + + + + &reftitle.examples; + + <function>MongoDB\Driver\BulkWriteCommandResult::getUpdateResults</function> example + + true]); +$bulk->insertOne('db.coll', ['x' => 1]); +$bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]); +$bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]); +$bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]); +$bulk->deleteMany('db.coll', []); + +$result = $manager->executeBulkWriteCommand($bulk); + +var_dump($result->getUpdateResults()->toPHP()); + +?> +]]> + + &example.outputs.similar; + + + object(stdClass)#7 (2) { + ["matchedCount"]=> + object(MongoDB\BSON\Int64)#5 (1) { + ["integer"]=> + string(1) "1" + } + ["modifiedCount"]=> + object(MongoDB\BSON\Int64)#6 (1) { + ["integer"]=> + string(1) "1" + } + } + ["2"]=> + object(stdClass)#11 (3) { + ["matchedCount"]=> + object(MongoDB\BSON\Int64)#8 (1) { + ["integer"]=> + string(1) "1" + } + ["modifiedCount"]=> + object(MongoDB\BSON\Int64)#9 (1) { + ["integer"]=> + string(1) "0" + } + ["upsertedId"]=> + object(MongoDB\BSON\ObjectId)#10 (1) { + ["oid"]=> + string(24) "67f7eb9b1f198bbcb880d575" + } + } + ["3"]=> + object(stdClass)#15 (3) { + ["matchedCount"]=> + object(MongoDB\BSON\Int64)#12 (1) { + ["integer"]=> + string(1) "1" + } + ["modifiedCount"]=> + object(MongoDB\BSON\Int64)#13 (1) { + ["integer"]=> + string(1) "0" + } + ["upsertedId"]=> + object(MongoDB\BSON\ObjectId)#14 (1) { + ["oid"]=> + string(24) "67f7eb9b1f198bbcb880d576" + } + } +} +]]> + + + + + + &reftitle.seealso; + + MongoDB\Driver\BulkWriteCommandResult::getMatchedCount + MongoDB\Driver\BulkWriteCommandResult::getModifiedCount + MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount + MongoDB\Driver\BulkWriteCommandResult::isAcknowledged + + + + + + diff --git a/reference/mongodb/mongodb/driver/bulkwritecommandresult/getupsertedcount.xml b/reference/mongodb/mongodb/driver/bulkwritecommandresult/getupsertedcount.xml new file mode 100644 index 000000000000..9cdf351b39de --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommandresult/getupsertedcount.xml @@ -0,0 +1,102 @@ + + + + + + MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount + Returns the number of documents upserted + + + + &reftitle.description; + + final public intMongoDB\Driver\BulkWriteCommandResult::getUpsertedCount + + + + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns the total number of documents upserted by all operations. + + + + + &reftitle.errors; + + &mongodb.throws.argumentparsing; + &mongodb.throws.unacknowledged; + + + + + &reftitle.examples; + + <function>MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount</function> example + +insertOne('db.coll', ['x' => 1]); +$bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]); +$bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]); +$bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]); +$bulk->deleteMany('db.coll', []); + +$result = $manager->executeBulkWriteCommand($bulk); + +var_dump($result->getUpsertedCount()); + +?> +]]> + + &example.outputs; + + + + + + + + &reftitle.seealso; + + MongoDB\Driver\BulkWriteCommandResult::getUpdateResults + MongoDB\Driver\BulkWriteCommandResult::isAcknowledged + + + + + + diff --git a/reference/mongodb/mongodb/driver/bulkwritecommandresult/isacknowledged.xml b/reference/mongodb/mongodb/driver/bulkwritecommandresult/isacknowledged.xml new file mode 100644 index 000000000000..2983f0c457c8 --- /dev/null +++ b/reference/mongodb/mongodb/driver/bulkwritecommandresult/isacknowledged.xml @@ -0,0 +1,126 @@ + + + + + + MongoDB\Driver\BulkWriteCommandResult::isAcknowledged + Returns whether the write was acknowledged + + + + &reftitle.description; + + final public boolMongoDB\Driver\BulkWriteCommandResult::isAcknowledged + + + + If the write is acknowledged, other fields will be available on the + MongoDB\Driver\BulkWriteCommandResult object. + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns &true; if the write was acknowledged, and &false; otherwise. + + + + + &reftitle.errors; + + &mongodb.throws.argumentparsing; + + + + + &reftitle.examples; + + <function>MongoDB\Driver\BulkWriteCommandResult::isAcknowledged</function> with acknowledged write concern + +insertOne('db.coll', ['x' => 1]); + +$result = $manager->executeBulkWriteCommand($bulk); + +var_dump($result->isAcknowledged()); + +?> +]]> + + &example.outputs; + + + + + + <function>MongoDB\Driver\BulkWriteCommandResult::isAcknowledged</function> with unacknowledged write concern + + false]); +$bulk->insertOne('db.coll', ['x' => 1]); + +$writeConcern = new MongoDB\Driver\WriteConcern(0); + +$result = $manager->executeBulkWriteCommand($bulk, ['writeConcern' => $writeConcern]); + +var_dump($result->isAcknowledged()); + +?> +]]> + + &example.outputs; + + + + + + + + &reftitle.seealso; + + MongoDB\Driver\WriteConcern + Write Concern reference + + + + + + diff --git a/reference/mongodb/mongodb/driver/exception/bulkwritecommandexception.xml b/reference/mongodb/mongodb/driver/exception/bulkwritecommandexception.xml new file mode 100644 index 000000000000..545da4f63955 --- /dev/null +++ b/reference/mongodb/mongodb/driver/exception/bulkwritecommandexception.xml @@ -0,0 +1,165 @@ + + + + + + The MongoDB\Driver\Exception\BulkWriteCommandException class + MongoDB\Driver\Exception\BulkWriteCommandException + + + + +
+ &reftitle.intro; + + Exception thrown due to failed execution of a + MongoDB\Driver\BulkWriteCommand. The methods of this + class provide more details of the error that occurred, including the error + reply and partial results from the bulk write. + +
+ + +
+ &reftitle.classsynopsis; + + + + MongoDB\Driver\Exception\BulkWriteCommandException + + + + + MongoDB\Driver\Exception\BulkWriteCommandException + + + + extends + MongoDB\Driver\Exception\ServerException + + + + MongoDB\Driver\Exception\Exception + + + + &Properties; + + private + MongoDB\BSON\Documentnull + errorReply + + + private + MongoDB\Driver\BulkWriteCommandResultnull + partialResult + + + private + array + writeConcernErrors + + + private + array + writeErrors + + + &InheritedProperties; + + + + + + &Methods; + + + &InheritedMethods; + + + + + + + +
+ + +
+ &reftitle.properties; + + + errorReply + + + Any top-level error that occurred when attempting to communicate with + the server or execute the bulk write. This value may be &null; if the + exception was thrown due to errors occurring on individual writes. + + + + + partialResult + + + A MongoDB\Driver\BulkWriteCommandResult reporting + the result of any successful operations that were performed before the + error was encountered. This value may not &null; if it cannot be + determined that at least one write was successfully performed (and + acknowledged). + + + + + writeConcernErrors + + + An array of any MongoDB\Driver\WriteConcernErrors + that occurred while executing the bulk write. This list may have + multiple items if more than one server command was required to execute + the bulk write. + + + + + writeErrors + + + An array of any MongoDB\Driver\WriteErrors + that occurred during the execution of individual write operations. Array + keys will correspond to the index of the write operation from + MongoDB\Driver\BulkWriteCommand. This map will + contain at most one entry if the bulk write was ordered. + + + + +
+ + + + + &reference.mongodb.mongodb.driver.exception.entities.bulkwritecommandexception; + + + + diff --git a/reference/mongodb/mongodb/driver/exception/bulkwritecommandexception/geterrorreply.xml b/reference/mongodb/mongodb/driver/exception/bulkwritecommandexception/geterrorreply.xml new file mode 100644 index 000000000000..bf44de90eb4f --- /dev/null +++ b/reference/mongodb/mongodb/driver/exception/bulkwritecommandexception/geterrorreply.xml @@ -0,0 +1,144 @@ + + + + + + MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply + Returns any top-level command error + + + + &reftitle.description; + + final public MongoDB\BSON\DocumentnullMongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply + + + + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns any top-level error that occurred when attempting to communicate + with the server or execute the bulk write. This value may be &null; if the + exception was thrown due to errors occurring on individual writes. + + + + + &reftitle.examples; + + <function>MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply</function> example + +executeCommand('admin', new MongoDB\Driver\Command([ + 'configureFailPoint' => 'failCommand', + 'mode' => ['times' => 1], + 'data' => [ + 'failCommands' => ['bulkWrite'], + 'errorCode' => 8, /* UnknownError */ + ], +])); + +$bulk = new MongoDB\Driver\BulkWriteCommand; +$bulk->insertOne('db.coll', ['x' => 1]); + +try { + $result = $manager->executeBulkWriteCommand($bulk); +} catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) { + var_dump($e->getErrorReply()?->toPHP()); +} + +?> +]]> + + &example.outputs.similar; + + + float(0) + ["errmsg"]=> + string(43) "Failing command via 'failCommand' failpoint" + ["code"]=> + int(8) + ["codeName"]=> + string(12) "UnknownError" + ["$clusterTime"]=> + object(stdClass)#10 (2) { + ["clusterTime"]=> + object(MongoDB\BSON\Timestamp)#6 (2) { + ["increment"]=> + string(1) "7" + ["timestamp"]=> + string(10) "1744319389" + } + ["signature"]=> + object(stdClass)#9 (2) { + ["hash"]=> + object(MongoDB\BSON\Binary)#7 (2) { + ["data"]=> + string(20) "" + ["type"]=> + int(0) + } + ["keyId"]=> + object(MongoDB\BSON\Int64)#8 (1) { + ["integer"]=> + string(1) "0" + } + } + } + ["operationTime"]=> + object(MongoDB\BSON\Timestamp)#11 (2) { + ["increment"]=> + string(1) "7" + ["timestamp"]=> + string(10) "1744319389" + } +} +]]> + + + + + + &reftitle.seealso; + + MongoDB\Driver\Manager::executeBulkWriteCommand + + + + + + diff --git a/reference/mongodb/mongodb/driver/exception/bulkwritecommandexception/getpartialresult.xml b/reference/mongodb/mongodb/driver/exception/bulkwritecommandexception/getpartialresult.xml new file mode 100644 index 000000000000..4301076defe1 --- /dev/null +++ b/reference/mongodb/mongodb/driver/exception/bulkwritecommandexception/getpartialresult.xml @@ -0,0 +1,134 @@ + + + + + + MongoDB\Driver\Exception\BulkWriteCommandException::getPartialResult + Returns the result of any successful write operations + + + + &reftitle.description; + + final public MongoDB\Driver\BulkWriteCommandResultnullMongoDB\Driver\Exception\BulkWriteCommandException::getPartialResult + + + + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns a MongoDB\Driver\BulkWriteCommandResult + reporting the result of any successful operations that were performed before + the error was encountered. The return value will be &null; if it cannot be + determined that at least one write was successfully performed (and + acknowledged). + + + + + &reftitle.examples; + + Partial result if at least one write is successful + +deleteMany('db.coll', []); +$bulk->insertOne('db.coll', ['_id' => 1]); +$bulk->insertOne('db.coll', ['_id' => 1]); + +try { + $result = $manager->executeBulkWriteCommand($bulk); +} catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) { + $result = $e->getPartialResult(); +} + +var_dump($result?->getInsertedCount()); + +?> +]]> + + &example.outputs; + + + + + + No partial result if no writes are successful + +deleteMany('db.coll', []); +$bulk->insertOne('db.coll', ['_id' => 1]); +$manager->executeBulkWriteCommand($bulk); + +$bulk = new MongoDB\Driver\BulkWriteCommand; +$bulk->insertOne('db.coll', ['_id' => 1]); + +try { + $result = $manager->executeBulkWriteCommand($bulk); +} catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) { + $result = $e->getPartialResult(); +} + +var_dump($result?->getInsertedCount()); + +?> +]]> + + &example.outputs; + + + + + + + + &reftitle.seealso; + + MongoDB\Driver\BulkWriteCommandResult + MongoDB\Driver\Manager::executeBulkWriteCommand + + + + + + diff --git a/reference/mongodb/mongodb/driver/exception/bulkwritecommandexception/getwriteconcernerrors.xml b/reference/mongodb/mongodb/driver/exception/bulkwritecommandexception/getwriteconcernerrors.xml new file mode 100644 index 000000000000..f38abe10c551 --- /dev/null +++ b/reference/mongodb/mongodb/driver/exception/bulkwritecommandexception/getwriteconcernerrors.xml @@ -0,0 +1,118 @@ + + + + + + MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors + Returns any write concern errors + + + + &reftitle.description; + + final public arrayMongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors + + + + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + An array of any MongoDB\Driver\WriteConcernErrors + that occurred while executing the bulk write. This list may have multiple + items if more than one server command was required to execute the bulk + write. + + + + + &reftitle.examples; + + <function>MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors</function> example + +insertOne('db.coll', ['x' => 1]); + +$writeConcern = new MongoDB\Driver\WriteConcern(50); + +try { + $result = $manager->executeBulkWriteCommand($bulk, ['writeConcern' => $writeConcern]); +} catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) { + var_dump($e->getWriteConcernErrors()); +} + +?> +]]> + + &example.outputs.similar; + + + object(MongoDB\Driver\WriteConcernError)#6 (3) { + ["message"]=> + string(29) "Not enough data-bearing nodes" + ["code"]=> + int(100) + ["info"]=> + object(stdClass)#8 (1) { + ["writeConcern"]=> + object(stdClass)#7 (3) { + ["w"]=> + int(50) + ["wtimeout"]=> + int(0) + ["provenance"]=> + string(14) "clientSupplied" + } + } + } +} +]]> + + + + + + &reftitle.seealso; + + MongoDB\Driver\Manager::executeBulkWriteCommand + MongoDB\Driver\WriteConcern + MongoDB\Driver\WriteConcernError + + + + + + diff --git a/reference/mongodb/mongodb/driver/exception/bulkwritecommandexception/getwriteerrors.xml b/reference/mongodb/mongodb/driver/exception/bulkwritecommandexception/getwriteerrors.xml new file mode 100644 index 000000000000..959423862f52 --- /dev/null +++ b/reference/mongodb/mongodb/driver/exception/bulkwritecommandexception/getwriteerrors.xml @@ -0,0 +1,124 @@ + + + + + + MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors + Returns any write errors + + + + &reftitle.description; + + final public arrayMongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors + + + + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + An array of any MongoDB\Driver\WriteErrors that + occurred during the execution of individual write operations. Array keys + will correspond to the index of the write operation from + MongoDB\Driver\BulkWriteCommand. This map will + contain at most one entry if the bulk write was ordered. + + + + + &reftitle.examples; + + <function>MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors</function> example + + false]); +$bulk->deleteMany('db.coll', []); +$bulk->insertOne('db.coll', ['_id' => 1]); +$bulk->insertOne('db.coll', ['_id' => 1]); +$bulk->insertOne('db.coll', ['_id' => 1]); + +try { + $result = $manager->executeBulkWriteCommand($bulk); +} catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) { + var_dump($e->getWriteErrors()); +} + +?> +]]> + + &example.outputs.similar; + + + object(MongoDB\Driver\WriteError)#5 (4) { + ["message"]=> + string(78) "E11000 duplicate key error collection: db.coll index: _id_ dup key: { _id: 1 }" + ["code"]=> + int(11000) + ["index"]=> + int(2) + ["info"]=> + object(stdClass)#6 (0) { + } + } + [3]=> + object(MongoDB\Driver\WriteError)#7 (4) { + ["message"]=> + string(78) "E11000 duplicate key error collection: db.coll index: _id_ dup key: { _id: 1 }" + ["code"]=> + int(11000) + ["index"]=> + int(3) + ["info"]=> + object(stdClass)#8 (0) { + } + } +} +]]> + + + + + + &reftitle.seealso; + + MongoDB\Driver\Manager::executeBulkWriteCommand + MongoDB\Driver\WriteError + + + + + + diff --git a/reference/mongodb/mongodb/driver/manager/executebulkwritecommand.xml b/reference/mongodb/mongodb/driver/manager/executebulkwritecommand.xml new file mode 100644 index 000000000000..f4343515a9fc --- /dev/null +++ b/reference/mongodb/mongodb/driver/manager/executebulkwritecommand.xml @@ -0,0 +1,211 @@ + + + + + + MongoDB\Driver\Manager::executeBulkWriteCommand + Execute write operations using the bulkWrite command + + + + &reftitle.description; + + final public MongoDB\Driver\BulkWriteCommandResultMongoDB\Driver\Manager::executeBulkWriteCommand + MongoDB\Driver\BulkWriteCommandbulk + arraynulloptions&null; + + + Executes one or more write operations on the primary server using the + bulkWrite + command introduced in MongoDB 8.0. + + + A MongoDB\Driver\BulkWriteCommand can be constructed + with one or more write operations of varying types (e.g. inserts, updates, + and deletes). Each write operation may target a different collection. + + + The default value for the "writeConcern" option will be + inferred from an active transaction (indicated by the + "session" option), followed by the + connection URI. + + + + + &reftitle.parameters; + + &mongodb.parameter.bulkwritecommand; + + options + + + + options + + + + Option + Type + Description + + + + &mongodb.option.session; + &mongodb.option.writeConcern; + + +
+ + + + + + + + &reftitle.returnvalues; + &mongodb.returns.bulkwritecommandresult; + + + + &reftitle.errors; + + Throws MongoDB\Driver\Exception\InvalidArgumentException if bulk does not contain any write operations. + Throws MongoDB\Driver\Exception\InvalidArgumentException if bulk has already been executed. MongoDB\Driver\BulkWriteCommand objects may not be executed multiple times. + &mongodb.throws.session-unacknowledged; + &mongodb.throws.std; + &mongodb.throws.bulkwritecommandexception; + Throws MongoDB\Driver\Exception\RuntimeException on other errors. + + + + + &reftitle.examples; + + Mixed write operations + + Mixed write operations (i.e. inserts, updates, and deletes) will be sent + to the server using a single + bulkWrite + command. + + +deleteMany('db.coll_one', []); +$bulk->deleteMany('db.coll_two', []); + +// Insert documents into two collections +$bulk->insertOne('db.coll_one', ['_id' => 1]); +$bulk->insertOne('db.coll_two', ['_id' => 2]); +$bulk->insertOne('db.coll_two', ['_id' => 3]); + +// Update a document in "coll_one" +$bulk->updateOne('db.coll_one', ['_id' => 1], ['$set' => ['x' => 1]]); + +$result = $manager->executeBulkWriteCommand($bulk); + +printf("Inserted %d document(s)\n", $result->getInsertedCount()); +printf("Updated %d document(s)\n", $result->getModifiedCount()); + +?> +]]> + + &example.outputs; + + + + + + Ordered write operations causing an error + +deleteMany('db.coll', []); +$bulk->insertOne('db.coll', ['_id' => 1]); +$bulk->insertOne('db.coll', ['_id' => 2]); +$bulk->insertOne('db.coll', ['_id' => 1]); +$bulk->insertOne('db.coll', ['_id' => 3]); + +try { + $result = $manager->executeBulkWriteCommand($bulk); +} catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) { + $result = $e->getPartialResult(); + + var_dump($e->getWriteErrors()); +} + +printf("Inserted %d document(s)\n", $result->getInsertedCount()); + +?> +]]> + + &example.outputs.similar; + + + object(MongoDB\Driver\WriteError)#5 (4) { + ["message"]=> + string(78) "E11000 duplicate key error collection: db.coll index: _id_ dup key: { _id: 1 }" + ["code"]=> + int(11000) + ["index"]=> + int(3) + ["info"]=> + object(stdClass)#6 (0) { + } + } +} +Inserted 2 document(s) +]]> + + + + + + &reftitle.seealso; + + MongoDB\Driver\BulkWriteCommand + MongoDB\Driver\BulkWriteCommandResult + MongoDB\Driver\WriteConcern + MongoDB\Driver\Server::executeBulkWriteCommand + + + + + + diff --git a/reference/mongodb/mongodb/driver/server/executebulkwritecommand.xml b/reference/mongodb/mongodb/driver/server/executebulkwritecommand.xml new file mode 100644 index 000000000000..b99bad1916da --- /dev/null +++ b/reference/mongodb/mongodb/driver/server/executebulkwritecommand.xml @@ -0,0 +1,113 @@ + + + + + + MongoDB\Driver\Server::executeBulkWriteCommand + Execute write operations on this server using the bulkWrite command + + + + &reftitle.description; + + final public MongoDB\Driver\BulkWriteCommandResultMongoDB\Driver\Server::executeBulkWriteCommand + MongoDB\Driver\BulkWriteCommandbulk + arraynulloptions&null; + + + Executes one or more write operations on this server using the + bulkWrite + command introduced in MongoDB 8.0. + + + A MongoDB\Driver\BulkWriteCommand can be constructed + with one or more write operations of varying types (e.g. inserts, updates, + and deletes). Each write operation may target a different collection. + + + The default value for the "writeConcern" option will be + inferred from an active transaction (indicated by the + "session" option), followed by the + connection URI. + + + + + &reftitle.parameters; + + &mongodb.parameter.bulkwritecommand; + + options + + + + options + + + + Option + Type + Description + + + + &mongodb.option.session; + &mongodb.option.writeConcern; + + +
+ + + + + + + + &reftitle.returnvalues; + &mongodb.returns.bulkwritecommandresult; + + + + &reftitle.errors; + + Throws MongoDB\Driver\Exception\InvalidArgumentException if bulk does not contain any write operations. + Throws MongoDB\Driver\Exception\InvalidArgumentException if bulk has already been executed. MongoDB\Driver\BulkWriteCommand objects may not be executed multiple times. + &mongodb.throws.session-unacknowledged; + &mongodb.throws.std; + &mongodb.throws.bulkwritecommandexception; + Throws MongoDB\Driver\Exception\RuntimeException on other errors. + + + + + &reftitle.seealso; + + MongoDB\Driver\BulkWriteCommand + MongoDB\Driver\BulkWriteCommandResult + MongoDB\Driver\WriteConcern + MongoDB\Driver\Manager::executeBulkWriteCommand + + + + + + diff --git a/reference/mongodb/versions.xml b/reference/mongodb/versions.xml index 6ea70d670935..9525120cb915 100644 --- a/reference/mongodb/versions.xml +++ b/reference/mongodb/versions.xml @@ -65,6 +65,7 @@ + @@ -100,6 +101,7 @@ + @@ -160,6 +162,27 @@ + + + + + + + + + + + + + + + + + + + + + @@ -211,6 +234,12 @@ + + + + + +