Skip to content

Commit 8935e6b

Browse files
jmikolajmikola
committed
Manager and Server executeBulkWriteCommand() methods
1 parent ded4c24 commit 8935e6b

File tree

4 files changed

+338
-0
lines changed

4 files changed

+338
-0
lines changed

‎language-snippets.ent

+12
Original file line numberDiff line numberDiff line change
@@ -3372,6 +3372,16 @@ local: {
33723372
</listitem>
33733373
</varlistentry>
33743374
'>
3375+
<!ENTITY mongodb.parameter.bulkwritecommand '
3376+
<varlistentry xmlns="http://docbook.org/ns/docbook">
3377+
<term><parameter>bulk</parameter> (<classname>MongoDB\Driver\BulkWriteCommand</classname>)</term>
3378+
<listitem>
3379+
<para>
3380+
The write(s) to execute.
3381+
</para>
3382+
</listitem>
3383+
</varlistentry>
3384+
'>
33753385
<!ENTITY mongodb.parameter.command '
33763386
<varlistentry xmlns="http://docbook.org/ns/docbook">
33773387
<term><parameter>command</parameter> (<classname>MongoDB\Driver\Command</classname>)</term>
@@ -3586,9 +3596,11 @@ local: {
35863596
'>
35873597
<!ENTITY mongodb.returns.cursor '<para xmlns="http://docbook.org/ns/docbook">Returns <classname>MongoDB\Driver\Cursor</classname> on success.</para>'>
35883598
<!ENTITY mongodb.returns.writeresult '<para xmlns="http://docbook.org/ns/docbook">Returns <classname>MongoDB\Driver\WriteResult</classname> on success.</para>'>
3599+
<!ENTITY mongodb.returns.bulkwritecommandresult '<para xmlns="http://docbook.org/ns/docbook">Returns <classname>MongoDB\Driver\BulkWriteCommandResult</classname> on success.</para>'>
35893600
<!ENTITY mongodb.throws.std '&mongodb.throws.argumentparsing;&mongodb.throws.connection;&mongodb.throws.authentication;'>
35903601
<!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>'>
35913602
<!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>'>
3603+
<!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>'>
35923604
<!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>'>
35933605
<!ENTITY mongodb.throws.argumentparsing '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname> on argument parsing errors.</member>'>
35943606
<!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/mongodb/driver/manager/executebulkwritecommand.xml

+211
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!-- $Revision$ -->
3+
4+
<refentry xml:id="mongodb-driver-manager.executebulkwritecommand" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5+
<refnamediv>
6+
<refname>MongoDB\Driver\Manager::executeBulkWriteCommand</refname>
7+
<refpurpose>Execute write operations using the bulkWrite command</refpurpose>
8+
</refnamediv>
9+
10+
<refsect1 role="description">
11+
&reftitle.description;
12+
<methodsynopsis>
13+
<modifier>final</modifier> <modifier>public</modifier> <type>MongoDB\Driver\BulkWriteCommandResult</type><methodname>MongoDB\Driver\Manager::executeBulkWriteCommand</methodname>
14+
<methodparam><type>MongoDB\Driver\BulkWriteCommand</type><parameter>bulk</parameter></methodparam>
15+
<methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>options</parameter><initializer>&null;</initializer></methodparam>
16+
</methodsynopsis>
17+
<para>
18+
Executes one or more write operations on the primary server using the
19+
<link xlink:href="&url.mongodb.docs.command;bulkWrite">bulkWrite</link>
20+
command introduced in MongoDB 8.0.
21+
</para>
22+
<para>
23+
A <classname>MongoDB\Driver\BulkWriteCommand</classname> can be constructed
24+
with one or more write operations of varying types (e.g. inserts, updates,
25+
and deletes). Each write operation may target a different collection.
26+
</para>
27+
<para>
28+
The default value for the <literal>"writeConcern"</literal> option will be
29+
inferred from an active transaction (indicated by the
30+
<literal>"session"</literal> option), followed by the
31+
<link linkend="mongodb-driver-manager.construct-uri">connection URI</link>.
32+
</para>
33+
</refsect1>
34+
35+
<refsect1 role="parameters">
36+
&reftitle.parameters;
37+
<variablelist>
38+
&mongodb.parameter.bulkwritecommand;
39+
<varlistentry>
40+
<term><parameter>options</parameter></term>
41+
<listitem>
42+
<para>
43+
<table>
44+
<title>options</title>
45+
<tgroup cols="3">
46+
<thead>
47+
<row>
48+
<entry>Option</entry>
49+
<entry>Type</entry>
50+
<entry>Description</entry>
51+
</row>
52+
</thead>
53+
<tbody>
54+
&mongodb.option.session;
55+
&mongodb.option.writeConcern;
56+
</tbody>
57+
</tgroup>
58+
</table>
59+
</para>
60+
</listitem>
61+
</varlistentry>
62+
</variablelist>
63+
</refsect1>
64+
65+
<refsect1 role="returnvalues">
66+
&reftitle.returnvalues;
67+
&mongodb.returns.bulkwritecommandresult;
68+
</refsect1>
69+
70+
<refsect1 role="errors">
71+
&reftitle.errors;
72+
<simplelist>
73+
<member>Throws <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname> if <parameter>bulk</parameter> does not contain any write operations.</member>
74+
<member>Throws <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname> if <parameter>bulk</parameter> has already been executed. <classname>MongoDB\Driver\BulkWriteCommand</classname> objects may not be executed multiple times.</member>
75+
&mongodb.throws.session-unacknowledged;
76+
&mongodb.throws.std;
77+
&mongodb.throws.bulkwritecommandexception;
78+
<member>Throws <classname>MongoDB\Driver\Exception\RuntimeException</classname> on other errors.</member>
79+
</simplelist>
80+
</refsect1>
81+
82+
<refsect1 role="examples">
83+
&reftitle.examples;
84+
<example>
85+
<title>Mixed write operations</title>
86+
<para>
87+
Mixed write operations (i.e. inserts, updates, and deletes) will be sent
88+
to the server using a single
89+
<link xlink:href="&url.mongodb.docs.command;bulkWrite">bulkWrite</link>
90+
command.
91+
</para>
92+
<programlisting role="php">
93+
<![CDATA[
94+
<?php
95+
96+
$manager = new MongoDB\Driver\Manager;
97+
98+
$bulk = new MongoDB\Driver\BulkWriteCommand;
99+
100+
// Delete documents from both collections
101+
$bulk->deleteMany('db.coll_one', []);
102+
$bulk->deleteMany('db.coll_two', []);
103+
104+
// Insert documents into two collections
105+
$bulk->insertOne('db.coll_one', ['_id' => 1]);
106+
$bulk->insertOne('db.coll_two', ['_id' => 2]);
107+
$bulk->insertOne('db.coll_two', ['_id' => 3]);
108+
109+
// Update a document in "coll_one"
110+
$bulk->updateOne('db.coll_one', ['_id' => 1], ['$set' => ['x' => 1]]);
111+
112+
$result = $manager->executeBulkWriteCommand($bulk);
113+
114+
printf("Inserted %d document(s)\n", $result->getInsertedCount());
115+
printf("Updated %d document(s)\n", $result->getModifiedCount());
116+
117+
?>
118+
]]>
119+
</programlisting>
120+
&example.outputs;
121+
<screen>
122+
<![CDATA[
123+
Inserted 3 document(s)
124+
Updated 1 document(s)
125+
]]>
126+
</screen>
127+
</example>
128+
<example>
129+
<title>Ordered write operations causing an error</title>
130+
<programlisting role="php">
131+
<![CDATA[
132+
<?php
133+
134+
$manager = new MongoDB\Driver\Manager;
135+
136+
$bulk = new MongoDB\Driver\BulkWriteCommand;
137+
138+
$bulk->deleteMany('db.coll', []);
139+
$bulk->insertOne('db.coll', ['_id' => 1]);
140+
$bulk->insertOne('db.coll', ['_id' => 2]);
141+
$bulk->insertOne('db.coll', ['_id' => 1]);
142+
$bulk->insertOne('db.coll', ['_id' => 3]);
143+
144+
try {
145+
$result = $manager->executeBulkWriteCommand($bulk);
146+
} catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
147+
$result = $e->getPartialResult();
148+
149+
var_dump($e->getWriteErrors());
150+
}
151+
152+
printf("Inserted %d document(s)\n", $result->getInsertedCount());
153+
154+
?>
155+
]]>
156+
</programlisting>
157+
&example.outputs.similar;
158+
<screen>
159+
<![CDATA[
160+
array(1) {
161+
[3]=>
162+
object(MongoDB\Driver\WriteError)#5 (4) {
163+
["message"]=>
164+
string(78) "E11000 duplicate key error collection: db.coll index: _id_ dup key: { _id: 1 }"
165+
["code"]=>
166+
int(11000)
167+
["index"]=>
168+
int(3)
169+
["info"]=>
170+
object(stdClass)#6 (0) {
171+
}
172+
}
173+
}
174+
Inserted 2 document(s)
175+
]]>
176+
</screen>
177+
</example>
178+
</refsect1>
179+
180+
<refsect1 role="seealso">
181+
&reftitle.seealso;
182+
<simplelist>
183+
<member><classname>MongoDB\Driver\BulkWriteCommand</classname></member>
184+
<member><classname>MongoDB\Driver\BulkWriteCommandResult</classname></member>
185+
<member><classname>MongoDB\Driver\WriteConcern</classname></member>
186+
<member><function>MongoDB\Driver\Server::executeBulkWriteCommand</function></member>
187+
</simplelist>
188+
</refsect1>
189+
190+
</refentry>
191+
192+
<!-- Keep this comment at the end of the file
193+
Local variables:
194+
mode: sgml
195+
sgml-omittag:t
196+
sgml-shorttag:t
197+
sgml-minimize-attributes:nil
198+
sgml-always-quote-attributes:t
199+
sgml-indent-step:1
200+
sgml-indent-data:t
201+
indent-tabs-mode:nil
202+
sgml-parent-document:nil
203+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
204+
sgml-exposed-tags:nil
205+
sgml-local-catalogs:nil
206+
sgml-local-ecat-files:nil
207+
End:
208+
vim600: syn=xml fen fdm=syntax fdl=2 si
209+
vim: et tw=78 syn=sgml
210+
vi: ts=1 sw=1
211+
-->

‎reference/mongodb/mongodb/driver/server/executebulkwritecommand.xml

+113
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!-- $Revision$ -->
3+
4+
<refentry xml:id="mongodb-driver-server.executebulkwritecommand" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5+
<refnamediv>
6+
<refname>MongoDB\Driver\Server::executeBulkWriteCommand</refname>
7+
<refpurpose>Execute write operations on this server using the bulkWrite command</refpurpose>
8+
</refnamediv>
9+
10+
<refsect1 role="description">
11+
&reftitle.description;
12+
<methodsynopsis>
13+
<modifier>final</modifier> <modifier>public</modifier> <type>MongoDB\Driver\BulkWriteCommandResult</type><methodname>MongoDB\Driver\Server::executeBulkWriteCommand</methodname>
14+
<methodparam><type>MongoDB\Driver\BulkWriteCommand</type><parameter>bulk</parameter></methodparam>
15+
<methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>options</parameter><initializer>&null;</initializer></methodparam>
16+
</methodsynopsis>
17+
<para>
18+
Executes one or more write operations on this server using the
19+
<link xlink:href="&url.mongodb.docs.command;bulkWrite">bulkWrite</link>
20+
command introduced in MongoDB 8.0.
21+
</para>
22+
<para>
23+
A <classname>MongoDB\Driver\BulkWriteCommand</classname> can be constructed
24+
with one or more write operations of varying types (e.g. inserts, updates,
25+
and deletes). Each write operation may target a different collection.
26+
</para>
27+
<para>
28+
The default value for the <literal>"writeConcern"</literal> option will be
29+
inferred from an active transaction (indicated by the
30+
<literal>"session"</literal> option), followed by the
31+
<link linkend="mongodb-driver-manager.construct-uri">connection URI</link>.
32+
</para>
33+
</refsect1>
34+
35+
<refsect1 role="parameters">
36+
&reftitle.parameters;
37+
<variablelist>
38+
&mongodb.parameter.bulkwritecommand;
39+
<varlistentry>
40+
<term><parameter>options</parameter></term>
41+
<listitem>
42+
<para>
43+
<table>
44+
<title>options</title>
45+
<tgroup cols="3">
46+
<thead>
47+
<row>
48+
<entry>Option</entry>
49+
<entry>Type</entry>
50+
<entry>Description</entry>
51+
</row>
52+
</thead>
53+
<tbody>
54+
&mongodb.option.session;
55+
&mongodb.option.writeConcern;
56+
</tbody>
57+
</tgroup>
58+
</table>
59+
</para>
60+
</listitem>
61+
</varlistentry>
62+
</variablelist>
63+
</refsect1>
64+
65+
<refsect1 role="returnvalues">
66+
&reftitle.returnvalues;
67+
&mongodb.returns.bulkwritecommandresult;
68+
</refsect1>
69+
70+
<refsect1 role="errors">
71+
&reftitle.errors;
72+
<simplelist>
73+
<member>Throws <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname> if <parameter>bulk</parameter> does not contain any write operations.</member>
74+
<member>Throws <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname> if <parameter>bulk</parameter> has already been executed. <classname>MongoDB\Driver\BulkWriteCommand</classname> objects may not be executed multiple times.</member>
75+
&mongodb.throws.session-unacknowledged;
76+
&mongodb.throws.std;
77+
&mongodb.throws.bulkwritecommandexception;
78+
<member>Throws <classname>MongoDB\Driver\Exception\RuntimeException</classname> on other errors.</member>
79+
</simplelist>
80+
</refsect1>
81+
82+
<refsect1 role="seealso">
83+
&reftitle.seealso;
84+
<simplelist>
85+
<member><classname>MongoDB\Driver\BulkWriteCommand</classname></member>
86+
<member><classname>MongoDB\Driver\BulkWriteCommandResult</classname></member>
87+
<member><classname>MongoDB\Driver\WriteConcern</classname></member>
88+
<member><function>MongoDB\Driver\Manager::executeBulkWriteCommand</function></member>
89+
</simplelist>
90+
</refsect1>
91+
92+
</refentry>
93+
94+
<!-- Keep this comment at the end of the file
95+
Local variables:
96+
mode: sgml
97+
sgml-omittag:t
98+
sgml-shorttag:t
99+
sgml-minimize-attributes:nil
100+
sgml-always-quote-attributes:t
101+
sgml-indent-step:1
102+
sgml-indent-data:t
103+
indent-tabs-mode:nil
104+
sgml-parent-document:nil
105+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
106+
sgml-exposed-tags:nil
107+
sgml-local-catalogs:nil
108+
sgml-local-ecat-files:nil
109+
End:
110+
vim600: syn=xml fen fdm=syntax fdl=2 si
111+
vim: et tw=78 syn=sgml
112+
vi: ts=1 sw=1
113+
-->

‎reference/mongodb/versions.xml

+2
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,7 @@
6767
<function name='mongodb\driver\manager::addsubscriber' from='mongodb &gt;=1.10.0'/>
6868
<function name='mongodb\driver\manager::createclientencryption' from='mongodb &gt;=1.7.0'/>
6969
<function name='mongodb\driver\manager::executebulkwrite' from='mongodb &gt;=1.0.0'/>
70+
<function name='mongodb\driver\manager::executebulkwritecommand' from='mongodb &gt;=2.1.0'/>
7071
<function name='mongodb\driver\manager::executecommand' from='mongodb &gt;=1.0.0'/>
7172
<function name='mongodb\driver\manager::executequery' from='mongodb &gt;=1.0.0'/>
7273
<function name='mongodb\driver\manager::executereadcommand' from='mongodb &gt;=1.4.0'/>
@@ -106,6 +107,7 @@
106107
<function name='mongodb\driver\server' from='mongodb &gt;=1.0.0'/>
107108
<function name='mongodb\driver\server::__construct' from='mongodb &gt;=1.0.0'/>
108109
<function name='mongodb\driver\server::executebulkwrite' from='mongodb &gt;=1.0.0'/>
110+
<function name='mongodb\driver\server::executebulkwritecommand' from='mongodb &gt;=2.1.0'/>
109111
<function name='mongodb\driver\server::executecommand' from='mongodb &gt;=1.0.0'/>
110112
<function name='mongodb\driver\server::executequery' from='mongodb &gt;=1.0.0'/>
111113
<function name='mongodb\driver\server::executereadcommand' from='mongodb &gt;=1.4.0'/>

0 commit comments

Comments
 (0)