archived-doc-es/reference/mongo/writeconcerns.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: fa909446a4cf15b5829ca87417db5ebcffc32a5c Maintainer: seros Status: ready -->
<!-- Reviewed: no -->

<chapter xml:id="mongo.writeconcerns" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Asuntos de Escritura (Write Concerns)</title>
 
 <para>
  MongoDB proporciona diferentes maneras de seleccionar la duración de una escritura a
  la base de datos. Estas formas se llaman <literal>Asuntos de
  Escritura</literal> y lo abarcan todo: desde ignorar completamente todos los errores,
  a seleccionar específicamente qué servidores son necesarios para confirmar la escritura
  antes de devolver la operación.
 </para>
 <para>
  Cuando una a escritura (como con <methodname>MongoCollection::insert</methodname>,
  <methodname>MongoCollection::update</methodname>, y
  <methodname>MongoCollection::remove</methodname>) se le proporciona una opción de
  Asunto de Escritura (<literal>"w"</literal>), el controlador enviará la consulta a MongoDB
  y luego proseguirá con un comando <literal>getLastError</literal>
  (<acronym>GLE</acronym>) con la opción de Asunto de Escritura al mismo tiempo.
  El servidor solo devuelve cuando la condición de Asunto de Escritura se verifica que se
  cumple, o la consulta expira (controlado con la
  opción<literal>"wtimeout"</literal>, <literal>10000</literal> milisegundos
  es lo predeterminado).
 </para>
 
 <warning>
  <para>
   Incluso si un comando <literal>getLastError</literal> expira, los datos
   habrán sido escritos probablemente en el servidor primario y serán
   replicados a todos los secundarios una vez se hayan finalizado con ellos.
  </para>
  <para>
   La típica razón para que una expiración ocurra es si se especifica un Asunto de
   Escritura que requiera confirmación de más servidores de los que estén disponibles
   en ese momento.
  </para>
 </warning>
 
 <para>
  Cuando se usan escrituras reconocidas y el conjunto de réplica ha fallado, el controlador
  se desconectará automáticamente del primario, lanzando una excepción, e
  intentará encontrar un nuevo primario en la siguiente operación (una aplicación debe
  decidir si reintentar o no la operación en el nuevo primario).
 </para>
 <para>
  Cuando se usan escrituras no reconocidas (w=0) y el conjunto de réplica ha fallado,
  no hay manera de que el controlador esté al tanto del campo, por lo que continuará
  y fallará en la escritura silenciosamente.
 </para>
 <para>
  El Asunto de Escritura predeterminado para <classname>MongoClient</classname> es
  <literal>1</literal>: operaciones de escritura reconocidas.
 </para>
 
 
 <para>
  <table xml:id="mongo.writeconcerns.options">
   <title>Asuntos de Escritura disponibles</title>
   <tgroup cols="3">
    <thead>
     <row>
      <entry>Asunto de Escritura</entry>
      <entry>Significado</entry>
      <entry>Descripción</entry>
     </row>
    </thead>
    <tbody>
     <!--
     <row>
      <entry>w=-1</entry>
      <entry>Errors ignored</entry>
      <entry>No errors, including network errors, will be checked at all</entry>
     </row>
-->
     <row>
      <entry>w=0</entry>
      <entry>Sin reconocimiento</entry>
      <entry>A una escritura no le seguirá una llamada a <acronym>GLE</acronym>, por lo que no será verificada ("dispara y olvida")</entry>
     </row>
     <row>
      <entry>w=1</entry>
      <entry>Con reconocimiento</entry>
      <entry>El servidor reconocerá la escritura (el primario en una configuración de conjunto de réplica)</entry>
     </row>
     <row>
      <entry>w=N</entry>
      <entry>Reconocimiento por parte del conjunto de réplica</entry>
      <entry>El servidor primario reconocerá la escritra, que
       será replicada a <literal>N-1</literal> secundarios.</entry>
     </row>
     <row>
      <entry>w=majority</entry>
      <entry>Reconociemiento por la mayoría</entry>
      <entry>La escritura será reconocia por la mayoría del conjunto de réplica (primario inclusive). Es un string reservado especial.</entry>
     </row>
     <row>
      <entry>w=&lt;tag set&gt;</entry>
      <entry>Reconocimiento por parte del conjunto de etiquetas del conjunto de réplica</entry>
      <entry>La escritura será reconocida por miembros de conjunto de etiquetas completo</entry>
     </row>
     <row>
      <entry>j=true</entry>
      <entry>Con diario</entry>
      <entry>El primario reconocerá la escritura y el diario será volcado a disco</entry>
     </row>
    </tbody>
   </tgroup>
  </table>
 </para>
 
 <simplesect xml:id="mongo.writeconcerns.setting">
  <title>Usar WriteConcerns</title>
  <para>
   Cada método que causa escrituras
   (<methodname>MongoCollection::insert</methodname>,
   <methodname>MongoCollection::update</methodname>, 
   <methodname>MongoCollection::remove</methodname>, y
   <methodname>MongoCollection::batchInsert</methodname>) permite un argumento
   opcional para enviar un conjunto de opciones al servidor de MongoDB. Con este array
   de opciones se puede establecer el WriteConcern como ilustra el siguiente ejemplo:
  </para>
  <example>
   <title>Pasar un WriteConcern a una operación de escritura</title>
   <programlisting role="php">
<![CDATA[
<?php
// Establecer w=0 para insertar:
$colección->insert($someDoc, array("w" => 0));

// Establecer w=majority para acutalizar:
$colección->update($someDoc, $someUpdates, array("w" => "majority"));

// Establecer w=5 y j=true para eliminar:
$colección->update($someDoc, array("w" => 5, "j" => true));

// Establecer w="AllDCs" para batchInsert:
$colección->update(array($someDoc1, $someDoc2), array("w" => "AllDCs"));
?>
]]>
   </programlisting>
  </example>
  <para>
   Además de establecer WriteConcerns por operación como un argumento de opción, es
   también posible establecer un WriteConcern predeterminado de diferentes formas.
  </para>
  <para>
   La primera forma es a través de la <link
   linkend="mongo.mongoclient.construct.parameters">cadena
   de conexión</link>. La cadena de conexión acpeta las opciones
   <literal>journal</literal>, <literal>w</literal>, y
   <literal>wTimeoutMS</literal>:
  </para>
  <example>
   <title>WriteConcerns en cadena de conexión</title>
   <programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient("mongodb://localhost/?journal=true&w=majority&wTimeoutMS=20000");
?>
]]>
   </programlisting>
  </example>
  
  <para>
   Desde la versión 1.5  del controlador, también es posible llamar a
   <methodname>MongoDB::setWriteConcern</methodname> y a
   <methodname>MongoCollection::setWriteConcern</methodname> para establecer un WriteConcern
   predeterminado para todas las operaciones creadas desde ese objeto
   <classname>MongoDB</classname> o <classname>MongoCollection</classname>
   específico:
  </para>
  <example>
   <title>MongoDB::setWriteConcern y MongoCollection::setWriteConcern</title>
   <programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient("mongodb://localhost/");
$d = $m->demoDb;
$c = $d->demoCollection;

// Establecer w=3 en el objeto de base de datos con un tiempo de espera de 25000ms
$d->setWriteConcern(3, 25000);

// Establecer w=majority en el objeto de colección sin cambiar el tiempo de espera
$c->setWriteConcern("majority");
?>
]]>
   </programlisting>
  </example>
 </simplesect>
 
 <simplesect xml:id="mongo.writeconcerns.unacknowledged">
  <title>Escrituras no reconocidas</title>
  <para>
   Al no requerir que el servidor reconozca las escrituras, estas se pueden realizar
   extremadamente rápido, pero no se sabrá si realmente han tenido éxito.
   Las escritura puede fallas por varias razones: si hay problemas de red, si un
   servidor de bases de datos falla, o si la escritura simplemente no era válida (p.ej., al
   escribir en una colección de sistema, o errores de clave duplicada).
  </para>
  <para>
   Durante el desarrollo, siempre se deberían usar escrituras reconocidas (para evitar
   errores inadvertidos, tales como errores de sintaxis, operadores no válidos, errores de clave duplicada
   , etc.). En la producción, las escrituras no reconocidas se pueden usar para datos "no importantes". Estos
   varían según la aplicación, pero generalmente son datos automáticos (al contrario de generados
   por el usuario), como el rastreo de clics o ubicaciones GPS, donde se pueden obtener
   miles de registros por segundo.
  </para>
  <para>
   Es muy recomendable realizar una escritura reconocida al final de una serie
   de escrituras no reconocidas. Esto no incurrirá en una penalización muy grande
   de redimiento, pero aún se puede capturar cualquier error que pudiera
   ocurrir.
  </para>
  <example xml:id="mongo.writeconcerns.unacknowledged-example">
   <title>Asunto de escritura no reconocido, seguido de una escritura reconocida</title>
   <programlisting role="php">
<![CDATA[
<?php
$colección->insert($documento, array("w" => 0));
$colección->update($criterios, $nuevonObj, array("w" => 0));
$colección->insert($otraCosa, array("w" => 0));
try {
    $colección->remove($something, array("w" => 1));
} catch(MongoCursorException $e) {
    /* Manejar la excepción... */
    /* Aquí se debería emitir consultas find() en los IDs generados para
    $otraCosa y $documento, para verificar que han sido escritos en la base de datos
    e intentar resolver dónde ocurrió algo en la serie. */
}
?>
]]>
   </programlisting>
   <para>
    Si la última escritura lanza una excepción, se sabrá que hay un problema
    en la base de datos.
   </para>
  </example>
 </simplesect>
 
 <simplesect xml:id="mongo.writeconcerns.acknowledged">
  <title>Escrituras reconocidas</title>
  <para>
   Este tipo de operaciones de escritura se asegura de que la base de datos ha
   aceptado la operación de escritura antes de indicar que ha tenido éxito. Si la escritura
   falla, lanzará una <classname>MongoCursorException</classname> con una
   explicación del fallo. El comportamiento predeterminado dee <classname>MongoClient</classname>
   es reconocer la escritura (w=1).
  </para>
  <para>
   Es posible especificar cuántos miembros de un conjunto de réplica tienen que
   reconocer la escritura (esto es, tiene que replicarla) antes de que la escritura se
   estime como reconocida y la operación devuelve.
   <example xml:id="mongo.writeconcerns.acknowledged-example">
    <title>Escrituras reconocidas</title>
    <programlisting role="php">
<![CDATA[
<?php
// Forzar el reconocimiento por parte del primario solamente
$colección->insert($doc, array("w" => 1));

// Forzar el reconocimiento por parte del primario, y otro miembro del
// conjunto de réplica
$colección->insert($doc, array("w" => 2));

// Forzar el reconocimiento por parte del primario, y otros seis miembros del
// conjunto de réplica (probablemente nunca debería hacer esto):
$colección->insert($doc, array("w" => 7));
?>
]]>
    </programlisting>
    <para>
     Recuerde seleccionar el Asunto de Escritura con cuidado. Si se tiene un
     conjunto de réplica con 5 miembros y se selecciona un Asunto de Escritura de
     <literal>4</literal>, se corre el riesgo de bloquear la escritura para siempre cuando
     un miembro del conjunto de réplica se desconecte por matenimiento o por un corte temporal
     de la red.
    </para>
   </example>
  </para>
  <warning>
   <para>
    El paso de un valor de tipo string al Asunto de Escritura posee un significado específico
    (Reconocimiento por parte del conjunto de etiquetas del conjunto de réplica). Tenga cuidado de
    <emphasis>NO</emphasis> usar valores de tipo string para números (esto es,
    <literal>array("w" => "1")</literal>) ya que serán tratados como el nombre de un conjunto de
    etiquetas.
   </para>
  </warning>
 </simplesect>
 
 <simplesect xml:id="mongo.writeconcerns.majority.acknowledged">
  <title>Escrituras reconocidas por la mayoría</title>
  <para>
   Usar la opción de Asunto de Escritura <literal>majority</literal> es la forma
   recomendada para escrituras que requieren sobrevidir al apocalipsis, ya que se asegurá
   de que la mayoría del conjunto de réplica tendrá la escritura y, por lo tanto, se
   garantizará que sobrevivirá a todos los escenarios de corte sospechosos usuales.
  </para>
  <example xml:id="mongo.writeconcerns.majority.acknowledged-example">
   <title>Escritura reconocida por la mayoría</title>
   <programlisting role="php">
<![CDATA[
<?php
$colección->insert($documento, array("w" => "majority"));
?>
]]>
   </programlisting>
  </example>
 </simplesect>
 
 <!-- FIXME
 <simplesect xml:id="mongo.writeconcerns.tagset">
  <title>ReplicaSet TagSet Acknowledged</title>
 </simplesect>
 -->
 
 <simplesect xml:id="mongo.writeconcerns.journal">
  <title>Escrituras con diario</title>
  <para>
   Al conectarse a un conjunto de réplica, el Asunto de Escritura predeterminado es hacer
   que solamente el servidor primario reconozca al escritura. Hay, sin embargo, una ventata de
   100 ms hasta que la escritura se escriba en el diario y sea volcada al disco. Es posible forzar
   a que la escritura sea escrita en el diario antes de que sea reconocia estableicendo la
   opción <literal>j</literal>:
   <example xml:id="mongo.writeconcerns.journalled">
    <title>Escritura reconocida y esctrita en el diario</title>
    <para>Forzar el volcado del diatio</para>
    <programlisting role="php">
<![CDATA[
<?php
$opciones = array(
    "w" => 1,
    "j" => true,
);
try {
    $colección->insert($documento, $opciones);
} catch(MongoCursorException $e) {
    /* manejar la excpeción */
}
?>
]]>
    </programlisting>
   </example>
  </para>
 </simplesect>
 
 <simplesect role="seealso">
  &reftitle.seealso;
  <simplelist>
   <member>
    <link xlink:href="&url.mongodb.docs;applications/replication/#replica-set-write-concern">MongoDB WriteConcern docs</link>
   </member>
  </simplelist>
 </simplesect>
 
 <simplesect role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>1.3.0</entry>
      <entry>
       Se introdujo <classname>MongoClient</classname>, cuyo comportamiento predeterminado es
       <link linkend="mongo.writeconcerns.acknowledged">reconocer</link> escrituras.
       La obsoleta <classname>Mongo</classname> no reconoce las escrituras de forma
       predeterminada.
      </entry>
     </row>
     <row>
      <entry>1.3.0</entry>
      <entry>
       La opción de escritura <literal>"safe"</literal> ahora es obsoleta y no
       está disponible con la nueva clase <classname>MongoClient</classname>.
       Use la opción <literal>"w"</literal> en su lugar.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </simplesect>
 
</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
-->