Skip to content

Commit ae93640

Browse files
jmikolajmikola
committed
MongoDB\Driver\BulkWriteCommand
1 parent 89b506b commit ae93640

File tree

11 files changed

+1400
-0
lines changed

11 files changed

+1400
-0
lines changed

‎reference/mongodb/mongodb.xml

+1
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;

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

+202
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+
-->

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

+184
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!-- $Revision$ -->
3+
4+
<refentry xml:id="mongodb-driver-bulkwritecommand.construct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5+
<refnamediv>
6+
<refname>MongoDB\Driver\BulkWriteCommand::__construct</refname>
7+
<refpurpose>Create a new BulkWriteCommand</refpurpose>
8+
</refnamediv>
9+
10+
<refsect1 role="description">
11+
&reftitle.description;
12+
<methodsynopsis>
13+
<modifier>public</modifier> <methodname>MongoDB\Driver\BulkWriteCommand::__construct</methodname>
14+
<methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>options</parameter><initializer>&null;</initializer></methodparam>
15+
</methodsynopsis>
16+
<para>
17+
Constructs a new <classname>MongoDB\Driver\BulkWriteCommand</classname>,
18+
which may be used to perform many insert, update, and delete operations on
19+
multiple collections in a single request using the
20+
<link xlink:href="&url.mongodb.docs.command;bulkWrite">bulkWrite</link>
21+
command introduced in MongoDB 8.0. This differs from
22+
<classname>MongoDB\Driver\BulkWrite</classname>, which is supported by all
23+
server versions but limited to a single collection.
24+
</para>
25+
<para>
26+
After all write operations have been added, this object may be executed with
27+
<methodname>MongoDB\Driver\Manager::executeBulkWriteCommand</methodname>.
28+
</para>
29+
</refsect1>
30+
31+
<refsect1 role="parameters">
32+
&reftitle.parameters;
33+
<variablelist>
34+
<varlistentry>
35+
<term><parameter>options</parameter> (<type>array</type>)</term>
36+
<listitem>
37+
<para>
38+
<table>
39+
<title>options</title>
40+
<tgroup cols="4">
41+
<thead>
42+
<row>
43+
<entry>Option</entry>
44+
<entry>Type</entry>
45+
<entry>Description</entry>
46+
<entry>Default</entry>
47+
</row>
48+
</thead>
49+
<tbody>
50+
<row>
51+
<entry>bypassDocumentValidation</entry>
52+
<entry><type>bool</type></entry>
53+
<entry>
54+
<para>
55+
If &true;, allows insert and update operations to circumvent
56+
document level validation.
57+
</para>
58+
</entry>
59+
<entry>&false;</entry>
60+
</row>
61+
<row>
62+
<entry>comment</entry>
63+
<entry><type>mixed</type></entry>
64+
<entry>
65+
<para>
66+
An arbitrary comment to help trace the operation through the
67+
database profiler, currentOp output, and logs.
68+
</para>
69+
</entry>
70+
</row>
71+
&mongodb.option.let;
72+
<row>
73+
<entry>ordered</entry>
74+
<entry><type>bool</type></entry>
75+
<entry>
76+
<para>
77+
Whether the operations in this bulk write should be executed in
78+
the order in which they were specified. If &false;, writes will
79+
continue to be executed if an individual write fails. If &true;,
80+
writes will stop executing if an individual write fails.
81+
</para>
82+
</entry>
83+
<entry>&true;</entry>
84+
</row>
85+
<row>
86+
<entry>verboseResults</entry>
87+
<entry><type>bool</type></entry>
88+
<entry>
89+
<para>
90+
Whether detailed results for each successful operation should be
91+
included in the returned
92+
<classname>MongoDB\Driver\BulkWriteCommandResult</classname>.
93+
</para>
94+
</entry>
95+
<entry>&false;</entry>
96+
</row>
97+
</tbody>
98+
</tgroup>
99+
</table>
100+
</para>
101+
</listitem>
102+
</varlistentry>
103+
</variablelist>
104+
</refsect1>
105+
106+
<refsect1 role="errors">
107+
&reftitle.errors;
108+
<simplelist>
109+
&mongodb.throws.argumentparsing;
110+
</simplelist>
111+
</refsect1>
112+
113+
<refsect1 role="examples">
114+
&reftitle.examples;
115+
<example>
116+
<title><function>MongoDB\Driver\BulkWriteCommand::__construct</function> example</title>
117+
<programlisting role="php">
118+
<![CDATA[
119+
<?php
120+
121+
$manager = new MongoDB\Driver\Manager;
122+
123+
$bulk = new MongoDB\Driver\BulkWriteCommand;
124+
125+
// Delete documents from both collections
126+
$bulk->deleteMany('db.coll_one', []);
127+
$bulk->deleteMany('db.coll_two', []);
128+
129+
// Insert documents into two collections
130+
$bulk->insertOne('db.coll_one', ['_id' => 1]);
131+
$bulk->insertOne('db.coll_two', ['_id' => 2]);
132+
$bulk->insertOne('db.coll_two', ['_id' => 3]);
133+
134+
// Update a document in "coll_one"
135+
$bulk->updateOne('db.coll_one', ['_id' => 1], ['$set' => ['x' => 1]]);
136+
137+
$result = $manager->executeBulkWriteCommand($bulk);
138+
139+
printf("Inserted %d document(s)\n", $result->getInsertedCount());
140+
printf("Updated %d document(s)\n", $result->getModifiedCount());
141+
142+
?>
143+
]]>
144+
</programlisting>
145+
&example.outputs;
146+
<screen>
147+
<![CDATA[
148+
Inserted 3 document(s)
149+
Updated 1 document(s)
150+
]]>
151+
</screen>
152+
</example>
153+
</refsect1>
154+
155+
<refsect1 role="seealso">
156+
&reftitle.seealso;
157+
<simplelist>
158+
<member><methodname>MongoDB\Driver\Manager::executeBulkWriteCommand</methodname></member>
159+
<member><classname>MongoDB\Driver\BulkWriteCommandResult</classname></member>
160+
</simplelist>
161+
</refsect1>
162+
163+
</refentry>
164+
165+
<!-- Keep this comment at the end of the file
166+
Local variables:
167+
mode: sgml
168+
sgml-omittag:t
169+
sgml-shorttag:t
170+
sgml-minimize-attributes:nil
171+
sgml-always-quote-attributes:t
172+
sgml-indent-step:1
173+
sgml-indent-data:t
174+
indent-tabs-mode:nil
175+
sgml-parent-document:nil
176+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
177+
sgml-exposed-tags:nil
178+
sgml-local-catalogs:nil
179+
sgml-local-ecat-files:nil
180+
End:
181+
vim600: syn=xml fen fdm=syntax fdl=2 si
182+
vim: et tw=78 syn=sgml
183+
vi: ts=1 sw=1
184+
-->

0 commit comments

Comments
 (0)