svn: /phpdoc/en/trunk/reference/mongo/ manual.xml writes.xml

From: Date: Thu, 26 Aug 2010 16:21:38 +0000
Subject: svn: /phpdoc/en/trunk/reference/mongo/ manual.xml writes.xml
Groups: php.doc.cvs 
Request: Send a blank email to doc-cvs+get-7045@lists.php.net to get a copy of this message
kristina Thu, 26 Aug 2010 16:21:38 +0000 Revision: http://svn.php.net/viewvc?view=revision&revision=302819 Log: more explanation of safe write options Changed paths: U phpdoc/en/trunk/reference/mongo/manual.xml A phpdoc/en/trunk/reference/mongo/writes.xml Modified: phpdoc/en/trunk/reference/mongo/manual.xml =================================================================== --- phpdoc/en/trunk/reference/mongo/manual.xml 2010-08-26 16:12:38 UTC (rev 302818) +++ phpdoc/en/trunk/reference/mongo/manual.xml 2010-08-26 16:21:38 UTC (rev 302819) @@ -8,8 +8,8 @@ &reference.mongo.ini; &reference.mongo.tutorial; &reference.mongo.connecting; + &reference.mongo.writes; &reference.mongo.queries; - &reference.mongo.updates; &reference.mongo.security; &reference.mongo.testing; &reference.mongo.trouble; Added: phpdoc/en/trunk/reference/mongo/writes.xml =================================================================== --- phpdoc/en/trunk/reference/mongo/writes.xml (rev 0) +++ phpdoc/en/trunk/reference/mongo/writes.xml 2010-08-26 16:21:38 UTC (rev 302819) @@ -0,0 +1,161 @@ +<?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[ + +$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[ + +$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 +--> + Property changes on: phpdoc/en/trunk/reference/mongo/writes.xml ___________________________________________________________________ Added: svn:keywords + Id Rev Revision Date LastChangedDate LastChangedRevision Author LastChangedBy HeadURL URL

« previous php.doc.cvs (#7045) next »