php-doc-en/reference/mongodb/mongodb/driver/bulkwrite.xml

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

<phpdoc:classref xml:id="class.mongodb-driver-bulkwrite" 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 MongoDB\Driver\BulkWrite class</title>
 <titleabbrev>MongoDB\Driver\BulkWrite</titleabbrev>

 <partintro>

<!-- {{{ MongoDB\Driver\BulkWrite intro -->
  <section xml:id="mongodb-driver-bulkwrite.intro">
   &reftitle.intro;
   <para>
    The <classname>MongoDB\Driver\BulkWrite</classname> 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
    <methodname>MongoDB\Driver\Manager::executeBulkWrite</methodname>.
   </para>
   <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.
   </para>
  </section>
<!-- }}} -->

  <section xml:id="mongodb-driver-bulkwrite.synopsis">
   &reftitle.classsynopsis;

<!-- {{{ Synopsis -->
   <classsynopsis>
    <ooclass><classname>MongoDB\Driver\BulkWrite</classname></ooclass>

<!-- {{{ Class synopsis -->
    <classsynopsisinfo>
     <modifier>final</modifier>
     <ooclass>
      <classname>MongoDB\Driver\BulkWrite</classname>
     </ooclass>
     
     <oointerface>
      <interfacename>Countable</interfacename>
     </oointerface>
    </classsynopsisinfo>
<!-- }}} -->
    
    <classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.mongodb-driver-bulkwrite')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[not(@role='procedural')])" />
   </classsynopsis>
<!-- }}} -->

  </section>

  <section xml:id="mongodb-driver-bulkwrite.examples">
   &reftitle.examples;

   <example>
    <title>Mixed write operations are grouped by type</title>
    <para>
     Mixed write operations (i.e. inserts, updates, and deletes) will be
     assembled into typed write commands to be sent sequentially to the server.
    </para>
    <programlisting role="php">
<![CDATA[
<?php

$bulk = new MongoDB\Driver\BulkWrite(['ordered' => true]);
$bulk->insert(['_id' => 1, 'x' => 1]);
$bulk->insert(['_id' => 2, 'x' => 2]);
$bulk->update(['x' => 2], ['$set' => ['x' => 1]]);
$bulk->insert(['_id' => 3, 'x' => 3]);
$bulk->delete(['x' => 1]);

?>
]]>
    </programlisting>
    <para>
     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.
    </para>
   </example>
   <example>
    <title>Ordered write operations causing an error</title>
    <programlisting role="php">
<![CDATA[
<?php

$bulk = new MongoDB\Driver\BulkWrite(['ordered' => true]);
$bulk->delete([]);
$bulk->insert(['_id' => 1]);
$bulk->insert(['_id' => 2]);
$bulk->insert(['_id' => 3, 'hello' => 'world']);
$bulk->update(['_id' => 3], ['$set' => ['hello' => 'earth']]);
$bulk->insert(['_id' => 4, 'hello' => 'pluto']);
$bulk->update(['_id' => 4], ['$set' => ['hello' => 'moon']]);
$bulk->insert(['_id' => 3]);
$bulk->insert(['_id' => 4]);
$bulk->insert(['_id' => 5]);

$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
$writeConcern = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY, 1000);

try {
    $result = $manager->executeBulkWrite('db.collection', $bulk, $writeConcern);
} catch (MongoDB\Driver\Exception\BulkWriteException $e) {
    $result = $e->getWriteResult();

    // Check if the write concern could not be fulfilled
    if ($writeConcernError = $result->getWriteConcernError()) {
        printf("%s (%d): %s\n",
            $writeConcernError->getMessage(),
            $writeConcernError->getCode(),
            var_export($writeConcernError->getInfo(), true)
        );
    }

    // Check if any write operations did not complete at all
    foreach ($result->getWriteErrors() as $writeError) {
        printf("Operation#%d: %s (%d)\n",
            $writeError->getIndex(),
            $writeError->getMessage(),
            $writeError->getCode()
        );
    }
} catch (MongoDB\Driver\Exception\Exception $e) {
    printf("Other error: %s\n", $e->getMessage());
    exit;
}

printf("Inserted %d document(s)\n", $result->getInsertedCount());
printf("Updated  %d document(s)\n", $result->getModifiedCount());

?>
]]>
    </programlisting>
   </example>
   &example.outputs;
   <screen>
<![CDATA[
Operation#7: E11000 duplicate key error index: db.collection.$_id_ dup key: { : 3 } (11000)
Inserted 4 document(s)
Updated  2 document(s)
]]>
   </screen>
   <para>
    If the write concern could not be fullfilled, the example above would output
    something like:
   </para>
   <screen>
<![CDATA[
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)
]]>
   </screen>
   <para>
    If we execute the example above, but allow for unordered writes:
   </para>
   <programlisting role="php">
<![CDATA[
<?php

$bulk = new MongoDB\Driver\BulkWrite(['ordered' => false]);
/* ... */

?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
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)
]]>
   </screen>
  </section>

  <section xml:id="mongodb-driver-bulkwrite.seealso">
   &reftitle.seealso;
   <simplelist>
    <member><methodname>MongoDB\Driver\Manager::executeBulkWrite</methodname></member>
    <member><classname>MongoDB\Driver\WriteResult</classname></member>
    <member><classname>MongoDB\Driver\WriteConcern</classname></member>
    <member><classname>MongoDB\Driver\WriteConcernError</classname></member>
    <member><classname>MongoDB\Driver\WriteError</classname></member>
   </simplelist>
  </section>

 </partintro>

 &reference.mongodb.mongodb.driver.entities.bulkwrite;

</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
-->