<!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 MongoWriteBatch class</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mongo.batch.html">Batch Classes</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mongowritebatch.add.html">MongoWriteBatch::add</a></div>
<div class="up"><a href="mongo.batch.html">Batch Classes</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="class.mongowritebatch" class="reference">
<h1 class="title">The MongoWriteBatch class</h1>
<div class="partintro"><p class="verinfo">(PECL mongo >=1.5.0)</p>
<div class="section" id="mongowritebatch.intro">
<h2 class="title">Introduction</h2>
<p class="para">
MongoWriteBatch is the base class for the <a href="class.mongoinsertbatch.html" class="classname">MongoInsertBatch</a>,
<a href="class.mongoupdatebatch.html" class="classname">MongoUpdateBatch</a> and <a href="class.mongodeletebatch.html" class="classname">MongoDeleteBatch</a> classes.
</p>
<p class="para">
MongoWriteBatch allows you to "batch up" multiple operations (of same type) and shipping them all
to MongoDB at the same time. This can be especially useful when operating on many documents at the
same time to reduce roundtrips.
</p>
<p class="para">
Prior to version 1.5.0 of the driver it was possible to use <span class="methodname"><a href="mongocollection.batchinsert.html" class="methodname">MongoCollection::batchInsert()</a></span>,
however, as of 1.5.0 that method is now discouraged.
</p>
<p class="para">
Note: This class is only available when talking to MongoDB 2.6.0 (and later) servers. It will throw
<a href="class.mongoprotocolexception.html" class="classname">MongoProtocolException</a> if attempting to use it on older MongoDB servers.
</p>
</div>
<div class="section" id="mongowritebatch.synopsis">
<h2 class="title">Class synopsis</h2>
<div class="classsynopsis">
<div class="ooclass"></div>
<div class="classsynopsisinfo">
<span class="ooclass">
<strong class="classname">MongoWriteBatch</strong>
</span>
{</div>
<div class="classsynopsisinfo classsynopsisinfo_comment">/* Constants */</div>
<div class="fieldsynopsis">
<span class="modifier">const</span>
<span class="type">int</span>
<var class="fieldsynopsis_varname"><a href="class.mongowritebatch.html#mongowritebatch.constants.command.insert"><var class="varname">COMMAND_INSERT</var></a></var>
<span class="initializer"> = 1</span>
;</div>
<div class="fieldsynopsis">
<span class="modifier">const</span>
<span class="type">int</span>
<var class="fieldsynopsis_varname"><a href="class.mongowritebatch.html#mongowritebatch.constants.command.update"><var class="varname">COMMAND_UPDATE</var></a></var>
<span class="initializer"> = 2</span>
;</div>
<div class="fieldsynopsis">
<span class="modifier">const</span>
<span class="type">int</span>
<var class="fieldsynopsis_varname"><a href="class.mongowritebatch.html#mongowritebatch.constants.command.delete"><var class="varname">COMMAND_DELETE</var></a></var>
<span class="initializer"> = 3</span>
;</div>
<div class="classsynopsisinfo classsynopsisinfo_comment">/* Methods */</div>
<div class="constructorsynopsis dc-description">
<span class="modifier">protected</span> <span class="methodname"><a href="mongowritebatch.construct.html" class="methodname">__construct</a></span>
( <span class="methodparam"><span class="type"><a href="class.mongocollection.html" class="type MongoCollection">MongoCollection</a></span> <code class="parameter">$collection</code></span>
[, <span class="methodparam"><span class="type">string</span> <code class="parameter">$batch_type</code></span>
[, <span class="methodparam"><span class="type">array</span> <code class="parameter">$write_options</code></span>
]] )</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span> <span class="type">bool</span> <span class="methodname"><a href="mongowritebatch.add.html" class="methodname">add</a></span>
( <span class="methodparam"><span class="type">array</span> <code class="parameter">$item</code></span>
)</div>
<div class="methodsynopsis dc-description">
<span class="modifier">final</span> <span class="modifier">public</span> <span class="type">array</span> <span class="methodname"><a href="mongowritebatch.execute.html" class="methodname">execute</a></span>
( <span class="methodparam"><span class="type">array</span> <code class="parameter">$write_options</code></span>
)</div>
}</div>
<div class="section" id="mongowritebatch.constants">
<h2 class="title">MongoWriteBatch types</h2>
<dl>
<dt id="mongowritebatch.constants.command.insert"><strong><code>MongoWriteBatch::COMMAND_INSERT</code></strong></dt>
<dd>
<p class="para">Create an Insert Write Batch</p>
</dd>
<dt id="mongowritebatch.constants.command.update"><strong><code>MongoWriteBatch::COMMAND_UPDATE</code></strong></dt>
<dd>
<p class="para">Create an Update Write Batch</p>
</dd>
<dt id="mongowritebatch.constants.command.delete"><strong><code>MongoWriteBatch::COMMAND_DELETE</code></strong></dt>
<dd>
<p class="para">Create an Delete Write Batch</p>
</dd>
</dl>
</div>
</div>
<div class="section" id="mongowritebatch.description">
<h2 class="title">Description</h2>
<p class="para">
When executing a batch by calling
<span class="methodname"><a href="mongowritebatch.execute.html" class="methodname">MongoWriteBatch::execute()</a></span>, MongoWriteBatch will send
up to <em>maxWriteBatchSize</em> (defaults to 1000) documents or
<em>maxBsonObjectSize</em> (defaults to 16777216 bytes), whichever
comes first.
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
Documents will never be partially transferred. When adding documents to the batch, that overflows the limit, a new
batch will be created and the document put into the new batch.
</p>
</p></blockquote>
</div>
<div class="section" id="mongowritebatch.errors">
<h2 class="title">Errors/Exceptions</h2>
<ul class="simplelist">
<li class="member"><a href="class.exception.html" class="classname">Exception</a> on parameter parsing failures</li>
<li class="member"><a href="class.exception.html" class="classname">Exception</a> on argument validation errors (e.g. missing keys)</li>
<li class="member"><a href="class.mongoprotocolexception.html" class="classname">MongoProtocolException</a> when talking to MongoDB server older then 2.6.0.</li>
<li class="member"><a href="class.mongoprotocolexception.html" class="classname">MongoProtocolException</a> on socket errors.</li>
<li class="member"><a href="class.mongowriteconcernexception.html" class="classname">MongoWriteConcernException</a> when a write fails due to <a href="mongo.writeconcerns.html" class="link">WriteConcerns</a></li>
</ul>
</div>
<div class="section" id="mongowritebatch.examples">
<h2 class="title">Examples</h2>
<div class="example" id="example-1665">
<p><strong>Example #1 <strong class="classname">MongoWriteBatch</strong> example</strong></p>
<div class="example-contents"><p>
Adding documents to a Insert batch and then execute it
</p></div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$mc </span><span style="color: #007700">= new </span><span style="color: #0000BB">MongoClient</span><span style="color: #007700">(</span><span style="color: #DD0000">"localhost"</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">$collection </span><span style="color: #007700">= </span><span style="color: #0000BB">$mc</span><span style="color: #007700">-></span><span style="color: #0000BB">selectCollection</span><span style="color: #007700">(</span><span style="color: #DD0000">"test"</span><span style="color: #007700">, </span><span style="color: #DD0000">"test"</span><span style="color: #007700">);<br /><br /><br /></span><span style="color: #0000BB">$docs </span><span style="color: #007700">= array();<br /></span><span style="color: #0000BB">$docs</span><span style="color: #007700">[] = array(</span><span style="color: #DD0000">"my" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"demo"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$docs</span><span style="color: #007700">[] = array(</span><span style="color: #DD0000">"is" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"working"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$docs</span><span style="color: #007700">[] = array(</span><span style="color: #DD0000">"pretty" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"well"</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">$batch </span><span style="color: #007700">= new </span><span style="color: #0000BB">MongoInsertBatch</span><span style="color: #007700">(</span><span style="color: #0000BB">$collection</span><span style="color: #007700">);<br />foreach(</span><span style="color: #0000BB">$docs </span><span style="color: #007700">as </span><span style="color: #0000BB">$document</span><span style="color: #007700">) {<br /> </span><span style="color: #0000BB">$batch</span><span style="color: #007700">-></span><span style="color: #0000BB">add</span><span style="color: #007700">(</span><span style="color: #0000BB">$document</span><span style="color: #007700">);<br />}<br /></span><span style="color: #0000BB">$retval </span><span style="color: #007700">= </span><span style="color: #0000BB">$batch</span><span style="color: #007700">-></span><span style="color: #0000BB">execute</span><span style="color: #007700">(array(</span><span style="color: #DD0000">"w" </span><span style="color: #007700">=> </span><span style="color: #0000BB">1</span><span style="color: #007700">));<br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$retval</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
array(2) {
["nInserted"]=>
int(3)
["ok"]=>
bool(true)
}
</pre></div>
</div>
</div>
</div>
</div>
<h2>Table of Contents</h2><ul class="chunklist chunklist_reference"><li><a href="mongowritebatch.add.html">MongoWriteBatch::add</a> — Adds a write operation to a batch</li><li><a href="mongowritebatch.construct.html">MongoWriteBatch::__construct</a> — Creates a new batch of write operations</li><li><a href="mongowritebatch.execute.html">MongoWriteBatch::execute</a> — Executes a batch of write operations</li></ul>
</div>
<hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mongo.batch.html">Batch Classes</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mongowritebatch.add.html">MongoWriteBatch::add</a></div>
<div class="up"><a href="mongo.batch.html">Batch Classes</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
