<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>The MongoDB\Driver\BulkWrite class</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mongodb-driver-query.construct.html">MongoDB\Driver\Query::__construct</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mongodb-driver-bulkwrite.construct.html">MongoDB\Driver\BulkWrite::__construct</a></div>
<div class="up"><a href="book.mongodb.html">MongoDB\Driver</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="class.mongodb-driver-bulkwrite" class="reference">
<h1 class="title">The MongoDB\Driver\BulkWrite class</h1>
<div class="partintro"><p class="verinfo">(mongodb >=1.0.0)</p>
<div class="section" id="mongodb-driver-bulkwrite.intro">
<h2 class="title">Introduction</h2>
<p class="para">
The <strong class="classname">MongoDB\Driver\BulkWrite</strong> collects one or more
write operations that should be sent to the server. After adding any
number of insert, update, and delete operations, the collection may be
executed via
<span class="methodname"><a href="mongodb-driver-manager.executebulkwrite.html" class="methodname">MongoDB\Driver\Manager::executeBulkWrite()</a></span>.
</p>
<p class="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.
</p>
</div>
<div class="section" id="mongodb-driver-bulkwrite.synopsis">
<h2 class="title">Class synopsis</h2>
<div class="classsynopsis">
<div class="ooclass"></div>
<div class="classsynopsisinfo">
<span class="modifier">final</span>
<span class="ooclass">
<strong class="classname">MongoDB\Driver\BulkWrite</strong>
</span>
<span class="oointerface">implements
<span class="interfacename"><a href="class.countable.html" class="interfacename">Countable</a></span>
</span>
{</div>
<div class="classsynopsisinfo classsynopsisinfo_comment">/* Methods */</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span> <span class="methodname"><a href="mongodb-driver-bulkwrite.construct.html" class="methodname">__construct</a></span>
([ <span class="methodparam"><span class="type">array</span> <code class="parameter">$options</code></span>
] )</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span> <span class="type">int</span> <span class="methodname"><a href="mongodb-driver-bulkwrite.count.html" class="methodname">count</a></span>
( <span class="methodparam">void</span>
)</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span> <span class="type">void</span> <span class="methodname"><a href="mongodb-driver-bulkwrite.delete.html" class="methodname">delete</a></span>
( <span class="methodparam"><span class="type"><span class="type array|object">array|object</span></span> <code class="parameter">$filter</code></span>
[, <span class="methodparam"><span class="type">array</span> <code class="parameter">$deleteOptions</code></span>
] )</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span> <span class="type">mixed</span> <span class="methodname"><a href="mongodb-driver-bulkwrite.insert.html" class="methodname">insert</a></span>
( <span class="methodparam"><span class="type"><span class="type array|object">array|object</span></span> <code class="parameter">$document</code></span>
)</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span> <span class="type">void</span> <span class="methodname"><a href="mongodb-driver-bulkwrite.update.html" class="methodname">update</a></span>
( <span class="methodparam"><span class="type"><span class="type array|object">array|object</span></span> <code class="parameter">$filter</code></span>
, <span class="methodparam"><span class="type"><span class="type array|object">array|object</span></span> <code class="parameter">$newObj</code></span>
[, <span class="methodparam"><span class="type">array</span> <code class="parameter">$updateOptions</code></span>
] )</div>
}</div>
</div>
<div class="section" id="mongodb-driver-bulkwrite.examples">
<h2 class="title">Examples</h2>
<div class="example" id="example-1696">
<p><strong>Example #1 Mixed write operations are grouped by type</strong></p>
<div class="example-contents"><p>
Mixed write operations (i.e. inserts, updates, and deletes) will be
assembled into typed write commands to be sent sequentially to the server.
</p></div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br />$bulk </span><span style="color: #007700">= new </span><span style="color: #0000BB">MongoDB</span><span style="color: #007700">\</span><span style="color: #0000BB">Driver</span><span style="color: #007700">\</span><span style="color: #0000BB">BulkWrite</span><span style="color: #007700">([</span><span style="color: #DD0000">'ordered' </span><span style="color: #007700">=> </span><span style="color: #0000BB">true</span><span style="color: #007700">]);<br /></span><span style="color: #0000BB">$bulk</span><span style="color: #007700">-></span><span style="color: #0000BB">insert</span><span style="color: #007700">([</span><span style="color: #DD0000">'_id' </span><span style="color: #007700">=> </span><span style="color: #0000BB">1</span><span style="color: #007700">, </span><span style="color: #DD0000">'x' </span><span style="color: #007700">=> </span><span style="color: #0000BB">1</span><span style="color: #007700">]);<br /></span><span style="color: #0000BB">$bulk</span><span style="color: #007700">-></span><span style="color: #0000BB">insert</span><span style="color: #007700">([</span><span style="color: #DD0000">'_id' </span><span style="color: #007700">=> </span><span style="color: #0000BB">2</span><span style="color: #007700">, </span><span style="color: #DD0000">'x' </span><span style="color: #007700">=> </span><span style="color: #0000BB">2</span><span style="color: #007700">]);<br /></span><span style="color: #0000BB">$bulk</span><span style="color: #007700">-></span><span style="color: #0000BB">update</span><span style="color: #007700">([</span><span style="color: #DD0000">'x' </span><span style="color: #007700">=> </span><span style="color: #0000BB">2</span><span style="color: #007700">], [</span><span style="color: #DD0000">'$set' </span><span style="color: #007700">=> [</span><span style="color: #DD0000">'x' </span><span style="color: #007700">=> </span><span style="color: #0000BB">1</span><span style="color: #007700">]]);<br /></span><span style="color: #0000BB">$bulk</span><span style="color: #007700">-></span><span style="color: #0000BB">insert</span><span style="color: #007700">([</span><span style="color: #DD0000">'_id' </span><span style="color: #007700">=> </span><span style="color: #0000BB">3</span><span style="color: #007700">, </span><span style="color: #DD0000">'x' </span><span style="color: #007700">=> </span><span style="color: #0000BB">3</span><span style="color: #007700">]);<br /></span><span style="color: #0000BB">$bulk</span><span style="color: #007700">-></span><span style="color: #0000BB">delete</span><span style="color: #007700">([</span><span style="color: #DD0000">'x' </span><span style="color: #007700">=> </span><span style="color: #0000BB">1</span><span style="color: #007700">]);<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>
Will result in four write commands (i.e. roundtrips) being executed. Since
the operations are ordered, the third insertion cannot be sent until the
preceding update is executed.
</p></div>
</div>
<div class="example" id="example-1697">
<p><strong>Example #2 Ordered write operations causing an error</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br />$bulk </span><span style="color: #007700">= new </span><span style="color: #0000BB">MongoDB</span><span style="color: #007700">\</span><span style="color: #0000BB">Driver</span><span style="color: #007700">\</span><span style="color: #0000BB">BulkWrite</span><span style="color: #007700">([</span><span style="color: #DD0000">'ordered' </span><span style="color: #007700">=> </span><span style="color: #0000BB">true</span><span style="color: #007700">]);<br /></span><span style="color: #0000BB">$bulk</span><span style="color: #007700">-></span><span style="color: #0000BB">delete</span><span style="color: #007700">([]);<br /></span><span style="color: #0000BB">$bulk</span><span style="color: #007700">-></span><span style="color: #0000BB">insert</span><span style="color: #007700">([</span><span style="color: #DD0000">'_id' </span><span style="color: #007700">=> </span><span style="color: #0000BB">1</span><span style="color: #007700">]);<br /></span><span style="color: #0000BB">$bulk</span><span style="color: #007700">-></span><span style="color: #0000BB">insert</span><span style="color: #007700">([</span><span style="color: #DD0000">'_id' </span><span style="color: #007700">=> </span><span style="color: #0000BB">2</span><span style="color: #007700">]);<br /></span><span style="color: #0000BB">$bulk</span><span style="color: #007700">-></span><span style="color: #0000BB">insert</span><span style="color: #007700">([</span><span style="color: #DD0000">'_id' </span><span style="color: #007700">=> </span><span style="color: #0000BB">3</span><span style="color: #007700">, </span><span style="color: #DD0000">'hello' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'world'</span><span style="color: #007700">]);<br /></span><span style="color: #0000BB">$bulk</span><span style="color: #007700">-></span><span style="color: #0000BB">update</span><span style="color: #007700">([</span><span style="color: #DD0000">'_id' </span><span style="color: #007700">=> </span><span style="color: #0000BB">3</span><span style="color: #007700">], [</span><span style="color: #DD0000">'$set' </span><span style="color: #007700">=> [</span><span style="color: #DD0000">'hello' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'earth'</span><span style="color: #007700">]]);<br /></span><span style="color: #0000BB">$bulk</span><span style="color: #007700">-></span><span style="color: #0000BB">insert</span><span style="color: #007700">([</span><span style="color: #DD0000">'_id' </span><span style="color: #007700">=> </span><span style="color: #0000BB">4</span><span style="color: #007700">, </span><span style="color: #DD0000">'hello' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'pluto'</span><span style="color: #007700">]);<br /></span><span style="color: #0000BB">$bulk</span><span style="color: #007700">-></span><span style="color: #0000BB">update</span><span style="color: #007700">([</span><span style="color: #DD0000">'_id' </span><span style="color: #007700">=> </span><span style="color: #0000BB">4</span><span style="color: #007700">], [</span><span style="color: #DD0000">'$set' </span><span style="color: #007700">=> [</span><span style="color: #DD0000">'hello' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'moon'</span><span style="color: #007700">]]);<br /></span><span style="color: #0000BB">$bulk</span><span style="color: #007700">-></span><span style="color: #0000BB">insert</span><span style="color: #007700">([</span><span style="color: #DD0000">'_id' </span><span style="color: #007700">=> </span><span style="color: #0000BB">3</span><span style="color: #007700">]);<br /></span><span style="color: #0000BB">$bulk</span><span style="color: #007700">-></span><span style="color: #0000BB">insert</span><span style="color: #007700">([</span><span style="color: #DD0000">'_id' </span><span style="color: #007700">=> </span><span style="color: #0000BB">4</span><span style="color: #007700">]);<br /></span><span style="color: #0000BB">$bulk</span><span style="color: #007700">-></span><span style="color: #0000BB">insert</span><span style="color: #007700">([</span><span style="color: #DD0000">'_id' </span><span style="color: #007700">=> </span><span style="color: #0000BB">5</span><span style="color: #007700">]);<br /><br /></span><span style="color: #0000BB">$manager </span><span style="color: #007700">= new </span><span style="color: #0000BB">MongoDB</span><span style="color: #007700">\</span><span style="color: #0000BB">Driver</span><span style="color: #007700">\</span><span style="color: #0000BB">Manager</span><span style="color: #007700">(</span><span style="color: #DD0000">'mongodb://localhost:27017'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$writeConcern </span><span style="color: #007700">= new </span><span style="color: #0000BB">MongoDB</span><span style="color: #007700">\</span><span style="color: #0000BB">Driver</span><span style="color: #007700">\</span><span style="color: #0000BB">WriteConcern</span><span style="color: #007700">(</span><span style="color: #0000BB">MongoDB</span><span style="color: #007700">\</span><span style="color: #0000BB">Driver</span><span style="color: #007700">\</span><span style="color: #0000BB">WriteConcern</span><span style="color: #007700">::</span><span style="color: #0000BB">MAJORITY</span><span style="color: #007700">, </span><span style="color: #0000BB">1000</span><span style="color: #007700">);<br /><br />try {<br /> </span><span style="color: #0000BB">$result </span><span style="color: #007700">= </span><span style="color: #0000BB">$manager</span><span style="color: #007700">-></span><span style="color: #0000BB">executeBulkWrite</span><span style="color: #007700">(</span><span style="color: #DD0000">'db.collection'</span><span style="color: #007700">, </span><span style="color: #0000BB">$bulk</span><span style="color: #007700">, </span><span style="color: #0000BB">$writeConcern</span><span style="color: #007700">);<br />} catch (</span><span style="color: #0000BB">MongoDB</span><span style="color: #007700">\</span><span style="color: #0000BB">Driver</span><span style="color: #007700">\</span><span style="color: #0000BB">Exception</span><span style="color: #007700">\</span><span style="color: #0000BB">BulkWriteException $e</span><span style="color: #007700">) {<br /> </span><span style="color: #0000BB">$result </span><span style="color: #007700">= </span><span style="color: #0000BB">$e</span><span style="color: #007700">-></span><span style="color: #0000BB">getWriteResult</span><span style="color: #007700">();<br /><br /> </span><span style="color: #FF8000">// Check if the write concern could not be fulfilled<br /> </span><span style="color: #007700">if (</span><span style="color: #0000BB">$writeConcernError </span><span style="color: #007700">= </span><span style="color: #0000BB">$result</span><span style="color: #007700">-></span><span style="color: #0000BB">getWriteConcernError</span><span style="color: #007700">()) {<br /> </span><span style="color: #0000BB">printf</span><span style="color: #007700">(</span><span style="color: #DD0000">"%s (%d): %s\n"</span><span style="color: #007700">,<br /> </span><span style="color: #0000BB">$writeConcernError</span><span style="color: #007700">-></span><span style="color: #0000BB">getMessage</span><span style="color: #007700">(),<br /> </span><span style="color: #0000BB">$writeConcernError</span><span style="color: #007700">-></span><span style="color: #0000BB">getCode</span><span style="color: #007700">(),<br /> </span><span style="color: #0000BB">var_export</span><span style="color: #007700">(</span><span style="color: #0000BB">$writeConcernError</span><span style="color: #007700">-></span><span style="color: #0000BB">getInfo</span><span style="color: #007700">(), </span><span style="color: #0000BB">true</span><span style="color: #007700">)<br /> );<br /> }<br /><br /> </span><span style="color: #FF8000">// Check if any write operations did not complete at all<br /> </span><span style="color: #007700">foreach (</span><span style="color: #0000BB">$result</span><span style="color: #007700">-></span><span style="color: #0000BB">getWriteErrors</span><span style="color: #007700">() as </span><span style="color: #0000BB">$writeError</span><span style="color: #007700">) {<br /> </span><span style="color: #0000BB">printf</span><span style="color: #007700">(</span><span style="color: #DD0000">"Operation#%d: %s (%d)\n"</span><span style="color: #007700">,<br /> </span><span style="color: #0000BB">$writeError</span><span style="color: #007700">-></span><span style="color: #0000BB">getIndex</span><span style="color: #007700">(),<br /> </span><span style="color: #0000BB">$writeError</span><span style="color: #007700">-></span><span style="color: #0000BB">getMessage</span><span style="color: #007700">(),<br /> </span><span style="color: #0000BB">$writeError</span><span style="color: #007700">-></span><span style="color: #0000BB">getCode</span><span style="color: #007700">()<br /> );<br /> }<br />} catch (</span><span style="color: #0000BB">MongoDB</span><span style="color: #007700">\</span><span style="color: #0000BB">Driver</span><span style="color: #007700">\</span><span style="color: #0000BB">Exception</span><span style="color: #007700">\</span><span style="color: #0000BB">Exception $e</span><span style="color: #007700">) {<br /> </span><span style="color: #0000BB">printf</span><span style="color: #007700">(</span><span style="color: #DD0000">"Other error: %s\n"</span><span style="color: #007700">, </span><span style="color: #0000BB">$e</span><span style="color: #007700">-></span><span style="color: #0000BB">getMessage</span><span style="color: #007700">());<br /> exit;<br />}<br /><br /></span><span style="color: #0000BB">printf</span><span style="color: #007700">(</span><span style="color: #DD0000">"Inserted %d document(s)\n"</span><span style="color: #007700">, </span><span style="color: #0000BB">$result</span><span style="color: #007700">-></span><span style="color: #0000BB">getInsertedCount</span><span style="color: #007700">());<br /></span><span style="color: #0000BB">printf</span><span style="color: #007700">(</span><span style="color: #DD0000">"Updated %d document(s)\n"</span><span style="color: #007700">, </span><span style="color: #0000BB">$result</span><span style="color: #007700">-></span><span style="color: #0000BB">getModifiedCount</span><span style="color: #007700">());<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
<p class="para">The above example will output:</p>
<div class="example-contents screen">
<div class="cdata"><pre>
Operation#7: E11000 duplicate key error index: db.collection.$_id_ dup key: { : 3 } (11000)
Inserted 4 document(s)
Updated 2 document(s)
</pre></div>
</div>
<p class="para">
If the write concern could not be fullfilled, the example above would output
something like:
</p>
<div class="example-contents screen">
<div class="cdata"><pre>
waiting for replication timed out (64): array (
'wtimeout' => true,
)
Operation#7: E11000 duplicate key error index: databaseName.collectionName.$_id_ dup key: { : 3 } (11000)
Inserted 4 document(s)
Updated 2 document(s)
</pre></div>
</div>
<p class="para">
If we execute the example above, but allow for unordered writes:
</p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br />$bulk </span><span style="color: #007700">= new </span><span style="color: #0000BB">MongoDB</span><span style="color: #007700">\</span><span style="color: #0000BB">Driver</span><span style="color: #007700">\</span><span style="color: #0000BB">BulkWrite</span><span style="color: #007700">([</span><span style="color: #DD0000">'ordered' </span><span style="color: #007700">=> </span><span style="color: #0000BB">false</span><span style="color: #007700">]);<br /></span><span style="color: #FF8000">/* ... */<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<p class="para">The above example will output:</p>
<div class="example-contents screen">
<div class="cdata"><pre>
Operation#7: E11000 duplicate key error index: db.collection.$_id_ dup key: { : 3 } (11000)
Operation#8: E11000 duplicate key error index: db.collection.$_id_ dup key: { : 4 } (11000)
Inserted 5 document(s)
Updated 2 document(s)
</pre></div>
</div>
</div>
<div class="section" id="mongodb-driver-bulkwrite.seealso">
<h2 class="title">See Also</h2>
<ul class="simplelist">
<li class="member"><span class="methodname"><a href="mongodb-driver-manager.executebulkwrite.html" class="methodname">MongoDB\Driver\Manager::executeBulkWrite()</a></span></li>
<li class="member"><a href="class.mongodb-driver-writeresult.html" class="classname">MongoDB\Driver\WriteResult</a></li>
<li class="member"><a href="class.mongodb-driver-writeconcern.html" class="classname">MongoDB\Driver\WriteConcern</a></li>
<li class="member"><a href="class.mongodb-driver-writeconcernerror.html" class="classname">MongoDB\Driver\WriteConcernError</a></li>
<li class="member"><a href="class.mongodb-driver-writeerror.html" class="classname">MongoDB\Driver\WriteError</a></li>
</ul>
</div>
</div>
<h2>Table of Contents</h2><ul class="chunklist chunklist_reference"><li><a href="mongodb-driver-bulkwrite.construct.html">MongoDB\Driver\BulkWrite::__construct</a> — Create a new BulkWrite</li><li><a href="mongodb-driver-bulkwrite.count.html">MongoDB\Driver\BulkWrite::count</a> — Count number of write operations in the bulk</li><li><a href="mongodb-driver-bulkwrite.delete.html">MongoDB\Driver\BulkWrite::delete</a> — Add a delete operation to the bulk</li><li><a href="mongodb-driver-bulkwrite.insert.html">MongoDB\Driver\BulkWrite::insert</a> — Add an insert operation to the bulk</li><li><a href="mongodb-driver-bulkwrite.update.html">MongoDB\Driver\BulkWrite::update</a> — Add an update operation to the bulk</li></ul>
</div>
<hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mongodb-driver-query.construct.html">MongoDB\Driver\Query::__construct</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mongodb-driver-bulkwrite.construct.html">MongoDB\Driver\BulkWrite::__construct</a></div>
<div class="up"><a href="book.mongodb.html">MongoDB\Driver</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
