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

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

<section xml:id="mongo.writes" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Writes</title>

 <section>
  <title>Safe Operations</title>
  <para>
   By default, the driver does not wait for a database response to writes
   (inserts, updates, and deletes).  This means that writes can be performed
   extremely quickly, but you don't know whether or not they actually succeeded.
   Writes can fail for a number of reasons: if there are network problems, if a 
   database server goes down, or if the write was simply invalid (e.g., writing 
   to a system collection).
  </para>
  <para>
   To get a response from the database, use the <literal>safe</literal> option,
   available for all types of writes.  This option will make sure that the 
   database has the write before returning success.  If the write failed, it
   will throw a <function>MongoCursorException</function> with an explanation of 
   the failure.
  </para>
  <para>
   While developing, you should always use safe writes (to protect against 
   inadvertent mistakes, such as duplicate key errors and similar).  In 
   production, unsafe writes can be used for "unimportant" data.  Unimportant
   data varies on application, but it's generally automatically (instead of user
   generated) data, such as click tracking or GPS locations, where you can get 
   thousands of records per second.
  </para>
  <para>
   To safely perform writes without incurring too large a performance penalty, 
   it is recommended that you do a safe write at the end of a series of writes.
   For example:
  </para>
  <programlisting role="php">
<![CDATA[
<?php
$collection->insert($someDoc);
$collection->update($criteria, $newObj);
$collection->insert($somethingElse);
$collection->remove($something, array("safe" => true));
?>
]]>
  </programlisting>
  <para>
   Then, if the last write throws an exception, you know that there's a problem
   with your database.
  </para>
  <para>
   There are a few other options available to ensure the safety of writes.  You
   can specify <literal>"fsync" =&gt; true</literal> to force the database to
   fsync all writes up to this point to disk (by default, MongoDB fsyncs writes
   once per minute).
  </para>
  <para>
   The safest way of doing a write is to use replication and specify the number
   of servers that must have this write before returning success.  (You should
   always use replication in production, see the Connecting section for more 
   information on replica sets.)
  </para>
  <programlisting role="php">
<![CDATA[
<?php
$collection->insert($someDoc, array("safe" => 3));
?>
]]>
  </programlisting>
  <para>
   If you specify <literal>"safe" =&gt; N</literal>, the MongoDB server will 
   make sure that at least <literal>N</literal> servers have a copy of the write
   before returning success.  So, if <literal>N</literal> is 3, the master and 
   two slaves must have the write.
  </para>
 </section>

 <section>
  <title>Updating Nested Objects</title>

  <para>
   Suppose we wish to change the name of a comment's author in this document:

   <programlisting>
<![CDATA[
{ 
    "_id" : ObjectId("4b06c282edb87a281e09dad9"), 
    "content" : "this is a blog post.",
    "comments" : 
    [
        {
            "author" : "Mike",
            "comment" : "I think that blah blah blah...",
        },
        {
            "author" : "John",
            "comment" : "I disagree."
        }
    ]
}
]]>
   </programlisting>

   In order to change an inner field, we use $set (so that all of the other 
   fields are not removed!) with the index of comment to change:

   <programlisting role="php">
<![CDATA[
<?php

$blog->update($criteria, array('$set' => array("comments.1" => array("author" => "Jim"))));

?>
]]>
   </programlisting>
  </para>
 </section>

 <section>
  <title>The Positional Operator</title>
  <para>
   The positional operator <literal>$</literal> is useful for updating objects 
   that are in arrays.  In the example above, for instance, suppose that we did
   not know the index of the comment that we needed to change, merely that we
   needed to change "John" to "Jim".  We can use <literal>$</literal> to do so.
  </para>
  <programlisting role="php">
<![CDATA[
<?php

$blog->update(
    array("comments.author" => "John"), 
    array('$set' => array('comments.$.author' => "Jim")));

?>
]]>
  </programlisting>
 </section>
</section>

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