Skip to content

Commit 187032b

Browse files
jmikolaalcaeus
jmikola
and
alcaeus
authored
MongoDB\Driver\BulkWriteCommand and related APIs (#4610)
* MongoDB\Driver\BulkWriteCommand * MongoDB\Driver\BulkWriteCommandResult * MongoDB\Driver\Exception\BulkWriteCommandException * Manager and Server executeBulkWriteCommand() methods * Clarify that BulkWriteCommandException exposes error details * Fix wrong duplicate property name --------- Co-authored-by: Andreas Braun <[email protected]>
1 parent a124543 commit 187032b

30 files changed

+3560
-0
lines changed

‎language-snippets.ent

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3431,6 +3431,16 @@ local: {
34313431
</listitem>
34323432
</varlistentry>
34333433
'>
3434+
<!ENTITY mongodb.parameter.bulkwritecommand '
3435+
<varlistentry xmlns="http://docbook.org/ns/docbook">
3436+
<term><parameter>bulk</parameter> (<classname>MongoDB\Driver\BulkWriteCommand</classname>)</term>
3437+
<listitem>
3438+
<para>
3439+
The write(s) to execute.
3440+
</para>
3441+
</listitem>
3442+
</varlistentry>
3443+
'>
34343444
<!ENTITY mongodb.parameter.command '
34353445
<varlistentry xmlns="http://docbook.org/ns/docbook">
34363446
<term><parameter>command</parameter> (<classname>MongoDB\Driver\Command</classname>)</term>
@@ -3645,9 +3655,11 @@ local: {
36453655
'>
36463656
<!ENTITY mongodb.returns.cursor '<para xmlns="http://docbook.org/ns/docbook">Returns <classname>MongoDB\Driver\Cursor</classname> on success.</para>'>
36473657
<!ENTITY mongodb.returns.writeresult '<para xmlns="http://docbook.org/ns/docbook">Returns <classname>MongoDB\Driver\WriteResult</classname> on success.</para>'>
3658+
<!ENTITY mongodb.returns.bulkwritecommandresult '<para xmlns="http://docbook.org/ns/docbook">Returns <classname>MongoDB\Driver\BulkWriteCommandResult</classname> on success.</para>'>
36483659
<!ENTITY mongodb.throws.std '&mongodb.throws.argumentparsing;&mongodb.throws.connection;&mongodb.throws.authentication;'>
36493660
<!ENTITY mongodb.throws.session-readwriteconcern '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname> if the <literal>"session"</literal> option is used with an associated transaction in combination with a <literal>"readConcern"</literal> or <literal>"writeConcern"</literal> option.</member>'>
36503661
<!ENTITY mongodb.throws.session-unacknowledged '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname> if the <literal>"session"</literal> option is used in combination with an unacknowledged write concern.</member>'>
3662+
<!ENTITY mongodb.throws.bulkwritecommandexception '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\BulkWriteCommandException</classname> on any write failure (e.g. command failure, write or write concern error)</member>'>
36513663
<!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>'>
36523664
<!ENTITY mongodb.throws.argumentparsing '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname> on argument parsing errors.</member>'>
36533665
<!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>'>

‎reference/mongodb/exceptions.xml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77

88
&reference.mongodb.mongodb.driver.exception.authenticationexception;
99
&reference.mongodb.mongodb.driver.exception.bulkwriteexception;
10+
&reference.mongodb.mongodb.driver.exception.bulkwritecommandexception;
1011
&reference.mongodb.mongodb.driver.exception.commandexception;
1112
&reference.mongodb.mongodb.driver.exception.connectionexception;
1213
&reference.mongodb.mongodb.driver.exception.connectiontimeoutexception;
@@ -51,6 +52,7 @@
5152
<listitem>
5253
<simpara><classname>MongoDB\Driver\Exception\ServerException</classname></simpara>
5354
<itemizedlist>
55+
<listitem><simpara><classname>MongoDB\Driver\Exception\BulkWriteCommandException</classname></simpara></listitem>
5456
<listitem><simpara><classname>MongoDB\Driver\Exception\CommandException</classname></simpara></listitem>
5557
<listitem><simpara><classname>MongoDB\Driver\Exception\ExecutionTimeoutException</classname></simpara></listitem>
5658
<listitem>

‎reference/mongodb/mongodb.xml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
&reference.mongodb.mongodb.driver.command;
1111
&reference.mongodb.mongodb.driver.query;
1212
&reference.mongodb.mongodb.driver.bulkwrite;
13+
&reference.mongodb.mongodb.driver.bulkwritecommand;
1314
&reference.mongodb.mongodb.driver.session;
1415
&reference.mongodb.mongodb.driver.clientencryption;
1516
&reference.mongodb.mongodb.driver.serverapi;
@@ -29,4 +30,5 @@
2930
&reference.mongodb.mongodb.driver.writeconcernerror;
3031
&reference.mongodb.mongodb.driver.writeerror;
3132
&reference.mongodb.mongodb.driver.writeresult;
33+
&reference.mongodb.mongodb.driver.bulkwritecommandresult;
3234
</part>

‎reference/mongodb/mongodb/driver/bulkwritecommand.xml

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!-- $Revision$ -->
3+
4+
<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">
5+
6+
<title>The MongoDB\Driver\BulkWriteCommand class</title>
7+
<titleabbrev>MongoDB\Driver\BulkWriteCommand</titleabbrev>
8+
9+
<partintro>
10+
11+
<!-- {{{ MongoDB\Driver\BulkWriteCommand intro -->
12+
<section xml:id="mongodb-driver-bulkwritecommand.intro">
13+
&reftitle.intro;
14+
<para>
15+
<classname>MongoDB\Driver\BulkWriteCommand</classname> collects one or more
16+
write operations that should be sent to the server using the
17+
<link xlink:href="&url.mongodb.docs.command;bulkWrite">bulkWrite</link>
18+
command introduced in MongoDB 8.0. After adding any number of insert,
19+
update, and delete operations, the command may be executed via
20+
<methodname>MongoDB\Driver\Manager::executeBulkWriteCommand</methodname>.
21+
</para>
22+
<para>
23+
Unlike <classname>MongoDB\Driver\BulkWrite</classname>, where all write
24+
operations must target the same collection, each write operation within
25+
<classname>MongoDB\Driver\BulkWriteCommand</classname> may target a
26+
different collection.
27+
</para>
28+
<para>
29+
Write operations may either be ordered (default) or unordered. Ordered write
30+
operations are sent to the server, in the order provided, for serial
31+
execution. If a write fails, any remaining operations will be aborted.
32+
Unordered operations are sent to the server in an arbitrary order
33+
where they may be executed in parallel. Any errors that occur are reported
34+
after all operations have been attempted.
35+
</para>
36+
</section>
37+
<!-- }}} -->
38+
39+
<section xml:id="mongodb-driver-bulkwritecommand.synopsis">
40+
&reftitle.classsynopsis;
41+
42+
<!-- {{{ Synopsis -->
43+
<classsynopsis>
44+
<ooclass><classname>MongoDB\Driver\BulkWriteCommand</classname></ooclass>
45+
46+
<!-- {{{ Class synopsis -->
47+
<classsynopsisinfo>
48+
<modifier>final</modifier>
49+
<ooclass>
50+
<classname>MongoDB\Driver\BulkWriteCommand</classname>
51+
</ooclass>
52+
53+
<oointerface>
54+
<interfacename>Countable</interfacename>
55+
</oointerface>
56+
</classsynopsisinfo>
57+
<!-- }}} -->
58+
59+
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
60+
<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')])" />
61+
</classsynopsis>
62+
<!-- }}} -->
63+
64+
</section>
65+
66+
<section xml:id="mongodb-driver-bulkwritecommand.examples">
67+
&reftitle.examples;
68+
69+
<example>
70+
<title>Mixed write operations</title>
71+
<para>
72+
Mixed write operations (i.e. inserts, updates, and deletes) will be sent
73+
to the server using a single
74+
<link xlink:href="&url.mongodb.docs.command;bulkWrite">bulkWrite</link>
75+
command.
76+
</para>
77+
<programlisting role="php">
78+
<![CDATA[
79+
<?php
80+
81+
$manager = new MongoDB\Driver\Manager;
82+
83+
$bulk = new MongoDB\Driver\BulkWriteCommand;
84+
85+
// Delete documents from both collections
86+
$bulk->deleteMany('db.coll_one', []);
87+
$bulk->deleteMany('db.coll_two', []);
88+
89+
// Insert documents into two collections
90+
$bulk->insertOne('db.coll_one', ['_id' => 1]);
91+
$bulk->insertOne('db.coll_two', ['_id' => 2]);
92+
$bulk->insertOne('db.coll_two', ['_id' => 3]);
93+
94+
// Update a document in "coll_one"
95+
$bulk->updateOne('db.coll_one', ['_id' => 1], ['$set' => ['x' => 1]]);
96+
97+
$result = $manager->executeBulkWriteCommand($bulk);
98+
99+
printf("Inserted %d document(s)\n", $result->getInsertedCount());
100+
printf("Updated %d document(s)\n", $result->getModifiedCount());
101+
102+
?>
103+
]]>
104+
</programlisting>
105+
&example.outputs;
106+
<screen>
107+
<![CDATA[
108+
Inserted 3 document(s)
109+
Updated 1 document(s)
110+
]]>
111+
</screen>
112+
</example>
113+
<example>
114+
<title>Ordered write operations causing an error</title>
115+
<programlisting role="php">
116+
<![CDATA[
117+
<?php
118+
119+
$manager = new MongoDB\Driver\Manager;
120+
121+
$bulk = new MongoDB\Driver\BulkWriteCommand;
122+
123+
$bulk->deleteMany('db.coll', []);
124+
$bulk->insertOne('db.coll', ['_id' => 1]);
125+
$bulk->insertOne('db.coll', ['_id' => 2]);
126+
$bulk->insertOne('db.coll', ['_id' => 1]);
127+
$bulk->insertOne('db.coll', ['_id' => 3]);
128+
129+
try {
130+
$result = $manager->executeBulkWriteCommand($bulk);
131+
} catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
132+
$result = $e->getPartialResult();
133+
134+
var_dump($e->getWriteErrors());
135+
}
136+
137+
printf("Inserted %d document(s)\n", $result->getInsertedCount());
138+
139+
?>
140+
]]>
141+
</programlisting>
142+
&example.outputs.similar;
143+
<screen>
144+
<![CDATA[
145+
array(1) {
146+
[3]=>
147+
object(MongoDB\Driver\WriteError)#5 (4) {
148+
["message"]=>
149+
string(78) "E11000 duplicate key error collection: db.coll index: _id_ dup key: { _id: 1 }"
150+
["code"]=>
151+
int(11000)
152+
["index"]=>
153+
int(3)
154+
["info"]=>
155+
object(stdClass)#6 (0) {
156+
}
157+
}
158+
}
159+
Inserted 2 document(s)
160+
]]>
161+
</screen>
162+
</example>
163+
</section>
164+
165+
<section xml:id="mongodb-driver-bulkwritecommand.seealso">
166+
&reftitle.seealso;
167+
<simplelist>
168+
<member><methodname>MongoDB\Driver\Manager::executeBulkWriteCommand</methodname></member>
169+
<member><classname>MongoDB\Driver\BulkWriteCommandResult</classname></member>
170+
<member><classname>MongoDB\Driver\Exception\BulkWriteCommandException</classname></member>
171+
<member><classname>MongoDB\Driver\WriteConcern</classname></member>
172+
<member><classname>MongoDB\Driver\WriteConcernError</classname></member>
173+
<member><classname>MongoDB\Driver\WriteError</classname></member>
174+
</simplelist>
175+
</section>
176+
177+
</partintro>
178+
179+
&reference.mongodb.mongodb.driver.entities.bulkwritecommand;
180+
181+
</reference>
182+
183+
<!-- Keep this comment at the end of the file
184+
Local variables:
185+
mode: sgml
186+
sgml-omittag:t
187+
sgml-shorttag:t
188+
sgml-minimize-attributes:nil
189+
sgml-always-quote-attributes:t
190+
sgml-indent-step:1
191+
sgml-indent-data:t
192+
indent-tabs-mode:nil
193+
sgml-parent-document:nil
194+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
195+
sgml-exposed-tags:nil
196+
sgml-local-catalogs:nil
197+
sgml-local-ecat-files:nil
198+
End:
199+
vim600: syn=xml fen fdm=syntax fdl=2 si
200+
vim: et tw=78 syn=sgml
201+
vi: ts=1 sw=1
202+
-->

0 commit comments

Comments
 (0)