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

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

<chapter xml:id="mongo.updates" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Updates</title>

 <para>
  Updates can be one of the most complicated operation available with 
  MongoDB.  They combine a query with an action, modifying documents that match
  the criteria.  They are also extremely powerful, allowing you to change 
  documents quickly and replace them altogether.  They are done in-place (when 
  possible) with little overhead. 
 </para>

 <section>
  <title>Modifying vs. replacing documents</title>

  <para>
   There are two types of updates you can use: modifying updates and replacing
   updates.  Modifying updates contain $-operators and change fields in a 
   document: they might increment counters, push new elements onto an array, 
   or change the type of a field.
  </para>

  <para>
   For example, a modifying update could add a new field to a document.
   <programlisting role="php">
<![CDATA[
<?php
/** suppose documents look like:
 * {"username" : "...", "password" : "...", "email" : "..."}
 */
$coll->update(array("username" => "joe"), array('$set' => array("twitter" => "@joe4153")));

/** now the document will look like:
 * {"username" : "joe", "password" : "...", "email" : "...", "twitter" : "@joe4153"}
 */
?>
]]>
   </programlisting>
  </para>

  <para>
   Replacing updates replace the entire matching document with a new document.
   They are generally not as efficient as using $-modifiers, but can be very
   usefully for complex operations or updates that can't be expressed in terms
   of $-operators.
  </para>

  <para>
   For example, a replacing update can completely change the structure of a
   document.
   <programlisting role="php">
<![CDATA[
<?php
/** suppose documents look like:
 * {"username" : "...", "password" : "...", "email" : "..."}
 */
$coll->update(array("username" => "joe"), array("userId" => 12345, "info" => array(
    "name" => "joe", "twitter" => "@joe4153", "email" => "..."), "likes" => array()));

/** now the document will look like:
 * {
 *     "userId" : 12345, 
 *     "info" : {
 *         "name" : "joe", 
 *         "twitter" : "@joe4153", 
 *         "email" : "..."
 *     },
 *     "likes" : []
 * }
 */
?>
]]>
   </programlisting>
  </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>
</chapter>

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