MongoDB\Driver\BulkWriteCommand and related APIs #4610
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,202 @@ | ||
| <?xml version="1.0" encoding="utf-8"?> | ||
| <!-- $Revision$ --> | ||
|
|
||
| <reference xml:id="class.mongodb-driver-bulkwritecommand" role="class" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude"> | ||
|
|
||
| <title>The MongoDB\Driver\BulkWriteCommand class</title> | ||
| <titleabbrev>MongoDB\Driver\BulkWriteCommand</titleabbrev> | ||
|
|
||
| <partintro> | ||
|
|
||
| <!-- {{{ MongoDB\Driver\BulkWriteCommand intro --> | ||
| <section xml:id="mongodb-driver-bulkwritecommand.intro"> | ||
| &reftitle.intro; | ||
| <para> | ||
| <classname>MongoDB\Driver\BulkWriteCommand</classname> collects one or more | ||
| write operations that should be sent to the server using the | ||
| <link xlink:href="&url.mongodb.docs.command;bulkWrite">bulkWrite</link> | ||
| command introduced in MongoDB 8.0. After adding any number of insert, | ||
| update, and delete operations, the command may be executed via | ||
| <methodname>MongoDB\Driver\Manager::executeBulkWriteCommand</methodname>. | ||
| </para> | ||
| <para> | ||
| Unlike <classname>MongoDB\Driver\BulkWrite</classname>, where all write | ||
| operations must target the same collection, each write operation within | ||
| <classname>MongoDB\Driver\BulkWriteCommand</classname> may target a | ||
| different collection. | ||
| </para> | ||
| <para> | ||
| 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. | ||
| </para> | ||
| </section> | ||
| <!-- }}} --> | ||
|
|
||
| <section xml:id="mongodb-driver-bulkwritecommand.synopsis"> | ||
| &reftitle.classsynopsis; | ||
|
|
||
| <!-- {{{ Synopsis --> | ||
| <classsynopsis> | ||
| <ooclass><classname>MongoDB\Driver\BulkWriteCommand</classname></ooclass> | ||
|
|
||
| <!-- {{{ Class synopsis --> | ||
| <classsynopsisinfo> | ||
| <modifier>final</modifier> | ||
| <ooclass> | ||
| <classname>MongoDB\Driver\BulkWriteCommand</classname> | ||
| </ooclass> | ||
|
|
||
| <oointerface> | ||
| <interfacename>Countable</interfacename> | ||
| </oointerface> | ||
| </classsynopsisinfo> | ||
| <!-- }}} --> | ||
|
|
||
| <classsynopsisinfo role="comment">&Methods;</classsynopsisinfo> | ||
| <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.mongodb-driver-bulkwritecommand')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[not(@role='procedural')])" /> | ||
| </classsynopsis> | ||
| <!-- }}} --> | ||
|
|
||
| </section> | ||
|
|
||
| <section xml:id="mongodb-driver-bulkwritecommand.examples"> | ||
| &reftitle.examples; | ||
|
|
||
| <example> | ||
|
There was a problem hiding this comment. These examples are shared with |
||
| <title>Mixed write operations</title> | ||
| <para> | ||
| Mixed write operations (i.e. inserts, updates, and deletes) will be sent | ||
| to the server using a single | ||
| <link xlink:href="&url.mongodb.docs.command;bulkWrite">bulkWrite</link> | ||
| command. | ||
| </para> | ||
| <programlisting role="php"> | ||
| <![CDATA[ | ||
| <?php | ||
|
|
||
| $manager = new MongoDB\Driver\Manager; | ||
|
|
||
| $bulk = new MongoDB\Driver\BulkWriteCommand; | ||
|
|
||
| // Delete documents from both collections | ||
| $bulk->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()); | ||
|
|
||
| ?> | ||
| ]]> | ||
| </programlisting> | ||
| &example.outputs; | ||
| <screen> | ||
| <![CDATA[ | ||
| Inserted 3 document(s) | ||
| Updated 1 document(s) | ||
| ]]> | ||
| </screen> | ||
| </example> | ||
| <example> | ||
| <title>Ordered write operations causing an error</title> | ||
| <programlisting role="php"> | ||
| <![CDATA[ | ||
| <?php | ||
|
|
||
| $manager = new MongoDB\Driver\Manager; | ||
|
|
||
| $bulk = new MongoDB\Driver\BulkWriteCommand; | ||
|
|
||
| $bulk->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()); | ||
|
|
||
| ?> | ||
| ]]> | ||
| </programlisting> | ||
| &example.outputs.similar; | ||
| <screen> | ||
| <![CDATA[ | ||
| array(1) { | ||
| [3]=> | ||
| 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) | ||
| ]]> | ||
| </screen> | ||
| </example> | ||
| </section> | ||
|
|
||
| <section xml:id="mongodb-driver-bulkwritecommand.seealso"> | ||
| &reftitle.seealso; | ||
| <simplelist> | ||
| <member><methodname>MongoDB\Driver\Manager::executeBulkWriteCommand</methodname></member> | ||
| <member><classname>MongoDB\Driver\BulkWriteCommandResult</classname></member> | ||
| <member><classname>MongoDB\Driver\Exception\BulkWriteCommandException</classname></member> | ||
| <member><classname>MongoDB\Driver\WriteConcern</classname></member> | ||
| <member><classname>MongoDB\Driver\WriteConcernError</classname></member> | ||
| <member><classname>MongoDB\Driver\WriteError</classname></member> | ||
| </simplelist> | ||
| </section> | ||
|
|
||
| </partintro> | ||
|
|
||
| &reference.mongodb.mongodb.driver.entities.bulkwritecommand; | ||
|
|
||
| </reference> | ||
|
|
||
| <!-- Keep this comment at the end of the file | ||
| Local variables: | ||
| mode: sgml | ||
| sgml-omittag:t | ||
| sgml-shorttag:t | ||
| sgml-minimize-attributes:nil | ||
| sgml-always-quote-attributes:t | ||
| sgml-indent-step:1 | ||
| sgml-indent-data:t | ||
| indent-tabs-mode:nil | ||
| sgml-parent-document:nil | ||
| sgml-default-dtd-file:"~/.phpdoc/manual.ced" | ||
| sgml-exposed-tags:nil | ||
| sgml-local-catalogs:nil | ||
| sgml-local-ecat-files:nil | ||
| End: | ||
| vim600: syn=xml fen fdm=syntax fdl=2 si | ||
| vim: et tw=78 syn=sgml | ||
| vi: ts=1 sw=1 | ||
| --> | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Note: this snippet may be introduced earlier for PHPC-2144, in which case this PR should be rebased.