MongoDB\Driver\BulkWriteCommand and related APIs #4610
Conversation
| <!ENTITY mongodb.throws.bulkwriteexception '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\BulkWriteException</classname> on any write failure (e.g. write error, failure to apply a write concern)</member>'> | ||
| <!ENTITY mongodb.throws.argumentparsing '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname> on argument parsing errors.</member>'> | ||
| <!ENTITY mongodb.throws.authentication '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\AuthenticationException</classname> if authentication is needed and fails.</member>'> | ||
| <!ENTITY mongodb.throws.connection '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\ConnectionException</classname> if connection to the server fails (for reasons other than authentication).</member>'> | ||
| <!ENTITY mongodb.throws.bson.unexpected '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\UnexpectedValueException</classname> 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 <link xlink:href="&url.mongodb.libbson;" xmlns:xlink="http://www.w3.org/1999/xlink">libbson</link> error.</member>'> | ||
| <!ENTITY mongodb.throws.unacknowledged '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\LogicException</classname> if the write was not acknowledged.</member>'> |
There was a problem hiding this comment.
Note: this snippet may be introduced earlier for PHPC-2144, in which case this PR should be rebased.
|
|
||
| $manager = new MongoDB\Driver\Manager; | ||
|
|
||
| // This example uses configureFailPoint to simulate a top-level command error |
There was a problem hiding this comment.
This seemed the only reliable way to produce a command failure on demand. Most non-server errors will end up being reported as an InvalidArgumentException (e.g. executing an empty BulkWriteCommand, or executing one twice) based on the libmongoc error domain and absence of a partial write result (per logic in phongo_execute_bulkwritecommand()).
| ?> | ||
| ]]> | ||
| </programlisting> | ||
| &example.outputs.similar; |
There was a problem hiding this comment.
I tried to be mindful to use &example.outputs.similar; instead of &example.outputs; for large dumps with variation due to times (e.g. ObjectIds or server responses), but please double check if I missed anything.
| </simplelist> | ||
| </refsect1> | ||
|
|
||
| <refsect1 role="examples"> |
There was a problem hiding this comment.
This borrows the same examples used in BulkWriteCommand's class documentation. The first example is also repeated in BulkWriteCommand::__construct().
Note: I omitted examples in Server::executeBulkWriteCommand() for consistency with executeBulkWrite(). Also, there would be nothing new to show there beyond an explicit call to Manager::selectServer().
| </fieldsynopsis> | ||
|
|
||
| <classsynopsisinfo role="comment">&InheritedProperties;</classsynopsisinfo> | ||
| <!-- <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('mongodb-driver-exception-serverexception.synopsis')/descendant::db:fieldsynopsis)" /> --> |
There was a problem hiding this comment.
For context, these <xi:include> blocks are commented out because the corresponding class has nothing for us to inherit. This is necessary to avoid XPointer evaluation failed warnings when building the docs, and is consistent with what we do in other exception classes.
|
|
||
| $result = $manager->executeBulkWriteCommand($bulk); | ||
|
|
||
| var_dump($result->getDeleteResults()->toPHP()); |
There was a problem hiding this comment.
I opted to use toPHP() instead of dumping the result MongoDB\BSON\Document directly to ensure users see that counts are returned as Int64 objects.
See PHPC-2568 for more context here.
| <section xml:id="mongodb-driver-bulkwritecommand.examples"> | ||
| &reftitle.examples; | ||
|
|
||
| <example> |
There was a problem hiding this comment.
These examples are shared with Manager::executeBulkWriteCommand(), and the first is also repeated for BulkWriteCommand::__construct(). This is notably the only example that demonstrates mixed write operations on different collections.
This depends on the following PRs and can remain in a draft state until they are merged:
https://jira.mongodb.org/browse/PHPC-2478