[prev in list] [next in list] [prev in thread] [next in thread]
List: php-doc-cvs
Subject: [DOC-CVS] =?utf-8?q?svn:_/phpdoc/en/trunk/reference/mongo/_manual.xml_writes.xml?=
From: Kristina_Chodorow <kristina () php ! net>
Date: 2010-08-26 16:21:38
Message-ID: svn-kristina-1282839698-302819-1873331855 () svn ! php ! net
[Download RAW message or body]
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" => 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" => 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
--
PHP Documentation Commits Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic