diff --git a/language-snippets.ent b/language-snippets.ent index 7875a8bf785a..528089dd72ec 100644 --- a/language-snippets.ent +++ b/language-snippets.ent @@ -3372,6 +3372,16 @@ local: { '> + + bulk (MongoDB\Driver\BulkWriteCommand) + + + The write(s) to execute. + + + +'> command (MongoDB\Driver\Command) @@ -3586,14 +3596,17 @@ 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.'> Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).'> Throws MongoDB\Driver\Exception\UnexpectedValueException if the input did not contain exactly one BSON document. Possible reasons include, but are not limited to, invalid BSON, extra data (after reading one BSON document), or an unexpected libbson error.'> +Throws MongoDB\Driver\Exception\LogicException if the write was not acknowledged.'> 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..c087ac020cea --- /dev/null +++ b/reference/mongodb/mongodb/driver/exception/bulkwritecommandexception.xml @@ -0,0 +1,163 @@ + + + + + + The MongoDB\Driver\Exception\BulkWriteCommandException class + MongoDB\Driver\Exception\BulkWriteCommandException + + + + +
+ &reftitle.intro; + + Exception thrown due to failed execution of a + MongoDB\Driver\BulkWriteCommand. + +
+ + +
+ &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 + errorReply + + + 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 ee52b8911915..9626c7b5b03a 100644 --- a/reference/mongodb/versions.xml +++ b/reference/mongodb/versions.xml @@ -67,6 +67,7 @@ + @@ -106,6 +107,7 @@ + @@ -168,6 +170,27 @@ + + + + + + + + + + + + + + + + + + + + + @@ -220,6 +243,12 @@ + + + + + +