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

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 452d71c53cb8f32e6a4df407aeab9dfbeeaa5fcf Maintainer: seros Status: ready -->
<!-- Reviewed: no -->
<chapter xml:id="mongo.queries" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Consultas</title>
 
 <simplesect xml:id="mongo.queries.secondaries">
  <title>Distribuyendo consultas a esclavos</title>
  
  <para>
   Todas las consultas (lecturas y escrituras) solamente se envian al miembro primario de un
   conjunto de réplicas de manera predeterminada. Sin embargo, esto es fácilmente configurable usando las
   <link linkend="mongo.readpreferences">Preferencias de lectura</link>, que permiten
   establecer algunas preferencias de lectura genéricas (tales como permitir que un secundario lea
   del servidor más cercano), y también proporcionar formas de dirigir específicamente un
   servidor en un país concreto, o incluso hardware, usando los
   <link linkend="mongo.readpreferences.tagsets">conjuntos de etiquetas de conjuntos de réplicas</link>.
  </para>
  <para>
   Las preferencias de lectura se pueden configurar en cualquier nivel del controlador:
   <simplelist>
    <member>Como parámetro de consulta u opción a <methodname>MongoClient::__construct</methodname></member>
    <member>Específicamente invocando a <methodname>MongoClient::setReadPreference</methodname></member>
    <member>A nivel de la base de datos con <methodname>MongoDB::setReadPreference</methodname></member>
    <member>A nivel de la colección con <methodname>MongoCollection::setReadPreference</methodname></member>
    <member>A nivel de cursor con <methodname>MongoCursor::setReadPreference</methodname> o <methodname>MongoCommandCursor::setReadPreference</methodname></member>
   </simplelist>
   Cada clase hereda su configuración de preferencias de lectura del contexto "padre".
  </para>
  <example xml:id="mongo.queries.secondaries.inheritence-example">
   <title>Herencia de las preferencias de lectura del nivel de la base de datos hacia el cursor</title>
   <programlisting role="php">
<![CDATA[
<?php
$db->setReadPreference(MongoClient::RP_SECONDARY_PREFERRED);
$c = $db->myCollection;

$cursor = $c->find();
?>
]]>
   </programlisting>
  </example>
  <para>
   En este ejemplo, la consulta se ejecutará en un secundario. La
   colección hereda <constant>MongoClient::RP_SECONDARY_PREFERRED</constant>
   de la base de datos y el cursor lo hereda de la colección.
  </para>
 </simplesect>
 
 <simplesect xml:id="mongo.queries.choosing.secondary">
  <title>Cómo se escogen los esclavos</title>
  
  <para>
   Cada instancia de <classname>MongoClient</classname> escoge su propio
   secundario utilizando el secundario disponible con el menor tiempo de respuesta. Es decir,
   si tuviéramos un cliente PHP en Europa y otro en Australia y tuviéramos un secundario en
   cada uno de estos centros de datos, podríamos hacer:
  </para>
  <example xml:id="mongo.queries.choosing.secondary-example">
   <programlisting role="php">
<![CDATA[
<?php
$options = array("replicaSet" => "setName", "readPreference" => MongoClient::RP_SECONDARY_PREFERRED);

// en el cliente de Australia
$m = new MongoClient("mongodb://primary,australianhost.secondary,europeanhost.secondary", $options);
$cursor = $m->foo->bar->find();
$cursor->getNext();
echo "Leyendo desde: ", $cursor->info()["server"], "\n";

// en el cliente de Europa
$m = new MongoClient("mongodb://primary,australianhost.secondary,europeanhost.secondary", $options);
$cursor = $m->foo->bar->find();
$cursor->getNext();
echo "Leyendo desde: ", $cursor->info()["server"], "\n";
?>
]]>
   </programlisting>
   &example.outputs.similar;
   <screen>
<![CDATA[
Reading from: australianHost
Reading from: europeanHost
]]>
   </screen>
   <para>
    Tenga en cuenta que se debe realizar una consulta antes de elegir un secundario:
    los secundarios los elige el controlador de forma retardada, y para cada consulta por separado.
   </para>
  </example>
  
  <para>
   Se puede ver los que el controlador piensa que es el estado actual de los miembros
   del conjunto ejecutando <methodname>MongoClient::getHosts</methodname> o
   <methodname>MongoClient::getConnections</methodname>.
  </para>
  
  <para>
   Si un secundario no es legible, el controlador enviará las lecturas al
   primario que se especificó con
   <constant>MongoClient::RP_SECONDARY_PREFERRED</constant>, que
   recurrirá a ejecutar una consulta en un primario si no estuviera disponible un secundario.
   Un servidor es considerado legible si su estado es 2 (SECONDARY) y su
   salud es 1. Se puede verificar esto con
   <methodname>MongoClient::getHosts</methodname> y
   <methodname>MongoClient::getConnections</methodname>.
  </para>
  
 </simplesect>
 <simplesect xml:id="mongo.queries.notes">
  <title>Notas aleatorias</title>
  
  <para>
   Las escrituras siempre se envian al primario y, de forma predeterminada, todas las lecturas
   son enviada también al primario.
  </para>
  <!--
   <para>
    The following database commands can be sent to secondaries when using the
    apropriate Read Preference:
    <simplelist>
     <member><methodname>MongoCollection::group</methodname></member>
     <member><methodname>MongoCollection::aggregate</methodname></member>
     <member><methodname>MongoCollection::distinct</methodname></member>
     <member><methodname>MongoCursor::count</methodname></member>
     <member>collStats</member>
     <member>dbStats</member>
     <member>geoNear</member>
     <member>geoSearch</member>
     <member>geoWalk</member>
     <member>inline mapreduce</member>
    </simplelist>
    All other commands are always sent to the primary.
   </para>
-->
 </simplesect>
 
 <simplesect xml:id="mongo.queries.querying">
  <title>Consultando por _id</title>
  <para>
   A cada objeto que se inserta se le asigna automáticamente un campo
   <literal>_id</literal> único, el cual, a menudo, es un campo útil para usarlo en
   consultas. Esto funciona de forma similar a la funcionalidad "obtener el último ID insertado",
   excepto que el <literal>_id</literal> es escogido por el <emphasis>cliente</emphasis>.
  </para>
  <para>
   Supongamos que queremos localizar el documento que acabamos de insertar. Las inserciones
   añaden un campo <literal>_id</literal> al documento, de modo que podemos realizar una consulta a partir de él:
   
   <example xml:id="mongo.queries.querying-example">
    <programlisting role="php">
<![CDATA[
<?php
$person = array("name" => "joe");

$people->insert($person);

// ahora $joe tiene un campo _id
$joe = $people->findOne(array("_id" => $person['_id']));
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   Salvo que se indique lo contrario, el campo <literal>_id</literal> será de tipo
   <classname>MongoId</classname>. El error más frecuente consiste en usar una cadena
   de texto que concuerde con un <classname>MongoId</classname>. Debe tenerse presente
   que son dos tipos de datos distintos, y no concuerdan, del mismo modo que el texto
   "array()" no es lo mismo que un array vacío. Por ejemplo:
   
   <example xml:id="mongo.queries.querying.wrong">
    <programlisting role="php">
<![CDATA[
<?php
$person = array("name" => "joe");

$people->insert($person);

// convertimos el _id a texto
$pid = $person['_id'] . "";

// FALLO - $pid es un texto, no un MongoId
$joe = $people->findOne(array("_id" => $pid));
?>
]]>
    </programlisting>
   </example>
  </para>
 </simplesect>
 
 <simplesect xml:id="mongo.queries.arrays">
  <title>Arrays</title>
  
  <para>
   Los arrays son especiales por varias razones. En primer lugar, hay dos tipos de arrays que
   MongoDB utiliza: arrays "normales" y arrays asociativos. Los arrays asociativos pueden tener
   cualquier combinación de claves y valores. Los arrays "normales" se definen como arrays
   con un índice numérico ascendente que comienza por 0 y se incrementa en uno por cada
   elemento. Estos son, normalmente, los arrays de PHP más comunes.
  </para>
  
  <para>
   Por ejemplo, si se quisiera guardar una lista de premios en un documento, podríamos
   poner:
  </para>
  
  <example xml:id="mongo.queries.arrays-example">
   <programlisting role="php">
<![CDATA[
<?php

$collection->save(array("awards" => array("gold", "silver", "bronze")));

?>
]]>
   </programlisting>
  </example>
  
  <para>
   Las consultas pueden llegar hasta los arrays en busca de elementos. Supongamos que queremos
   encontrar todos los documentos que contienen un elemento de un array con un determinado valor. Por ejemplo,
   documentos con un premio "gold", como por ejemplo:
  </para>
  
  <screen>
<![CDATA[
{ "_id" : ObjectId("4b06c282edb87a281e09dad9"), "awards" : ["gold", "silver", "bronze"]}
]]>
  </screen>
  
  <para>
   Esto puede lograrse con una única consulta, ignorando el hecho de que "awards" es
   un array:
  </para>
  
  <example xml:id="mongo.queries.arrays-example-2">
   <programlisting role="php">
<![CDATA[
<?php

  $cursor = $collection->find(array("awards" => "gold"));

?>
]]>
   </programlisting>
  </example>
  
  <para>
   Supongamos que estamos consultando un objeto más complejo, si cada elemento del array
   fuera un objeto en sí mismo, como en:
  </para>
  
  <screen>
<![CDATA[
{
     "_id" : ObjectId("4b06c282edb87a281e09dad9"),
     "awards" :
     [
        {
            "first place" : "gold"
        },
        {
            "second place" : "silver"
        },
        {
            "third place" :  "bronze"
        }
     ]
}
]]>
  </screen>
  
  <para>
   Incluso aquí, ignorando que se trata de un array, podemos usar la misma
   notación para consultar al subobjeto:
  </para>
  
  <example xml:id="mongo.queries.querying-arrays-nested">
   <programlisting role="php">
<![CDATA[
<?php

$cursor = $collection->find(array("awards.first place" => "gold"));

?>
]]>
   </programlisting>
  </example>
  
  <para>
   Debe tenerse en cuenta que no importa que haya espacios en los nombres de campos
   (pese a que sea mejor no usarlos, sólo por mantenerlo más
   legible).
  </para>
  
  <para>
   Puede también usarse un array para consultar un determinado número de posibles valores. Por
   ejemplo, si buscáramos documentos "gold" o "copper", podríamos hacer:
  </para>
  
  <example xml:id="mongo.queries.querying-arrays-in">
   <programlisting role="php">
<![CDATA[
<?php

$cursor = $collection->find(array("awards" => array('$in' => array("gold", "copper"))));

?>
]]>
   </programlisting>
  </example>
 </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.1</entry>
      <entry>
       Several database commands can now be executed on secondaries.
      </entry>
     </row>
-->
     <row>
      <entry>1.3.0</entry>
      <entry>
       Se introdujo el framwork <link linkend="mongo.readpreferences">Preferencias
       de Lectura</link> para poder tener más control sobre
       las lecturas de secundarios.
      </entry>
     </row>
     <row>
      <entry>1.3.0</entry>
      <entry>
       Uso obsoleto de <literal>slaveOkay</literal>, la alternativa es <link
       linkend="mongo.readpreferences">Preferencias de Lectura</link>.
      </entry>
     </row>
     <row>
      <entry>1.1.0</entry>
      <entry>
       Se introdujo la posibilidad de enviar lecturas a secundarios de miembros de conjuntos
       de réplicas usando <methodname>Mongo::setSlaveOkay</methodname>
      </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
-->