php-doc-en/reference/mongo/mongowritebatch.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->

<phpdoc:classref xml:id="class.mongowritebatch" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">

 <title>The MongoWriteBatch class</title>
 <titleabbrev>MongoWriteBatch</titleabbrev>

 <partintro>

<!-- {{{ MongoWriteBatch intro -->
  <section xml:id="mongowritebatch.intro">
   &reftitle.intro;
   <para>
    MongoWriteBatch is the base class for the <classname>MongoInsertBatch</classname>,
    <classname>MongoUpdateBatch</classname> and <classname>MongoDeleteBatch</classname> classes.
   </para>
   <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.
   </para>
   <para>
    Prior to version 1.5.0 of the driver it was possible to use <methodname>MongoCollection::batchInsert</methodname>,
    however, as of 1.5.0 that method is now discouraged.
   </para>
   <para>
    Note: This class is only available when talking to MongoDB 2.6.0 (and later) servers. It will throw
    <classname>MongoProtocolException</classname> if attempting to use it on older MongoDB servers.
   </para>
  </section>
<!-- }}} -->

  <section xml:id="mongowritebatch.synopsis">
   &reftitle.classsynopsis;

<!-- {{{ Synopsis -->
   <classsynopsis>
    <ooclass><classname>MongoWriteBatch</classname></ooclass>

<!-- {{{ Class synopsis -->
    <classsynopsisinfo>
     <ooclass>
      <classname>MongoWriteBatch</classname>
     </ooclass>
    </classsynopsisinfo>
<!-- }}} -->
    
    <classsynopsisinfo role="comment">&Constants;</classsynopsisinfo>
    <fieldsynopsis>
     <modifier>const</modifier>
     <type>int</type>
     <varname linkend="mongowritebatch.constants.command.insert">MongoWriteBatch::COMMAND_INSERT</varname>
     <initializer>1</initializer>
    </fieldsynopsis>
    <fieldsynopsis>
     <modifier>const</modifier>
     <type>int</type>
     <varname linkend="mongowritebatch.constants.command.update">MongoWriteBatch::COMMAND_UPDATE</varname>
     <initializer>2</initializer>
    </fieldsynopsis>
    <fieldsynopsis>
     <modifier>const</modifier>
     <type>int</type>
     <varname linkend="mongowritebatch.constants.command.delete">MongoWriteBatch::COMMAND_DELETE</varname>
     <initializer>3</initializer>
    </fieldsynopsis>

    <classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.mongowritebatch')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[not(@role='procedural')])" />
    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.mongowritebatch')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[not(@role='procedural')])" />
   </classsynopsis>
<!-- }}} -->

   <section xml:id="mongowritebatch.constants">
    <title>MongoWriteBatch types</title>
    <variablelist>

     <varlistentry xml:id="mongowritebatch.constants.command.insert">
      <term><constant>MongoWriteBatch::COMMAND_INSERT</constant></term>
      <listitem>
       <para>Create an Insert Write Batch</para>
      </listitem>
     </varlistentry>

     <varlistentry xml:id="mongowritebatch.constants.command.update">
      <term><constant>MongoWriteBatch::COMMAND_UPDATE</constant></term>
      <listitem>
       <para>Create an Update Write Batch</para>
      </listitem>
     </varlistentry>

     <varlistentry xml:id="mongowritebatch.constants.command.delete">
      <term><constant>MongoWriteBatch::COMMAND_DELETE</constant></term>
      <listitem>
       <para>Create an Delete Write Batch</para>
      </listitem>
     </varlistentry>

    </variablelist>
   </section>
  </section>

  <section xml:id="mongowritebatch.description">
   &reftitle.description;
   <para>
    When executing a batch, by calling <methodname>MongoWriteBatch::execute</methodname>, MongoWriteBatch will send over
    <link xlink:href="url.mongodb.dochub.maxWriteBatchSize">maxWriteBatchSize</link> (defaults to 1000) documents or 
    up to <link xlink:href="url.mongodb.dochub.maxBsonObjectSize">maxBsonObjectSize</link> (defaults to 16777216 bytes), whichever comes first. 
   </para>
   <note>
    <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.
    </para>
   </note>
  </section>

  <section xml:id="mongowritebatch.errors">
   &reftitle.errors;
   <simplelist>
    <member><classname>Exception</classname> on parameter parsing failures</member>
    <member><classname>Exception</classname> on argument validation errors (e.g. missing keys)</member>
    <member><classname>MongoProtocolException</classname> when talking to MongoDB server older then 2.6.0.</member>
    <member><classname>MongoProtocolException</classname> on socket errors.</member>
    <member><classname>MongoWriteConcernException</classname> when a write fails due to <link linkend="mongo.writeconcerns">WriteConcerns</link></member>
   </simplelist>
  </section>

  <section xml:id="mongowritebatch.examples">
   &reftitle.examples;
   <example xml:id="mongowritebatch.example.basic">
    <title><classname>MongoWriteBatch</classname> example</title>
    <para>
     Adding documents to a Insert batch and then execute it
    </para>
    <programlisting role="php">
<![CDATA[
<?php
$mc = new MongoClient("localhost");

$collection = $mc->selectCollection("test", "test");


$docs = array();
$docs[] = array("my" => "demo");
$docs[] = array("is" => "working");
$docs[] = array("pretty" => "well");

$batch = new MongoInsertBatch($collection);
foreach($docs as $document) {
    $batch->add($document);
}
$retval = $batch->execute(array("w" => 1));
var_dump($retval);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
array(2) {
  ["nInserted"]=>
  int(3)
  ["ok"]=>
  bool(true)
}
]]>
    </screen>
   </example>
  </section>

 </partintro>

 &reference.mongo.entities.mongowritebatch;

</phpdoc:classref>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->