archived-doc-es/reference/mongo/mongocursor/batchsize.xml

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

<refentry xml:id="mongocursor.batchsize" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>MongoCursor::batchSize</refname>
  <refpurpose>Limita el número de elementos devueltos en un lote</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <modifier>public</modifier> <type>MongoCursor</type><methodname>MongoCursor::batchSize</methodname>
   <methodparam><type>int</type><parameter>batchSize</parameter></methodparam>
  </methodsynopsis>
  <para>
   Un cursor normalmente obtiene un lote de objetos de resultados y los almacena
   localmente. Este método establece el valor de batchSize para configurar la cantidad de
   documentos obtenidos desde el servidor en viaje de ida y vuelta. Sin embargo, nunca
   devolverá más documentos que los que no sobrepasen el límite del tamaño del lote
   (normalmente 4 MB).  
  </para>
 </refsect1>
 
 <refsect1 role="parameters">
  &reftitle.parameters;  
  <para>
   <variablelist>
    <varlistentry>
     <term>
      <parameter>batchSize</parameter>
     </term>
     <listitem>
      <para>
       El número de resultados a devolver por lote. Cada lote requiere un
       viaje de ida y vuelta al servidor.
      </para>
      <para>
       Si <parameter>batchSize</parameter> is <emphasis>2 o
       más</emphasis>, representa el tamaño de cada lote de objetos recuperados.
       Se puede ajustar para optimizar el rendimiento y limitar la transferencia de datos.
      </para>
      <para>
       Si <parameter>batchSize</parameter> es <literal>1</literal> o negativo, limitará
       el número de documentos devueltos al valor absoluto de batchSize,
       y el cursor se cerrará. Por ejemplo, si
       batchSize es <literal>-10</literal>, el servidor devolverá un máximo
       de 10 documentos siempre que quepan en 4 MB; luego cerrará el cursor.
      </para>
      <warning>
       <para>
        Un <parameter>batchSize</parameter> de <literal>1</literal> es especial, y
        significa lo mismo que <literal>-1</literal>, esto es, un valor de
        <literal>1</literal> hace que el cursor solamente devuelva
        <emphasis>un</emphasis> documento.
       </para>
      </warning>
      <para>
       Observe que esta característica se diferencia de
       <function>MongoCursor::limit</function> en que los documentos deben ajustarse dentro
       de un tamaño máximo, por lo que elimina la necesidad de enviar una petición para cerrar el
       cursor en el lado del servidor. El tamaño del lote se puede cambiar incluso después de que un
       cursor sea iterado, en cuyo caso el ajuste se aplicará solamente a la obtención del siguiente lote.
      </para>
      <para>
       Esto no anula al límite de MongoDB de la cantidad de datos que serán devueltos
       al cliente (esto es, si se establece el tamaño del lote a 1,000,000,000, MongoDB todavía
       devolverá 4-16 MB de resultados por lote). 
      </para>
      <para>
       Para asegurarse de un comportamiento consistente, las reglas de
       <function>MongoCursor::batchSize</function> y
       <function>MongoCursor::limit</function> son un poco
       complejas, aunque funcionan "como se esperaba". Las reglas son: los límites fuertes anulan
       a los ligeros, con preferencia dada a <function>MongoCursor::limit</function>
       sobre <function>MongoCursor::batchSize</function>.  Después, lo que sea establecido
       y sea menor que el otro, tomará precedencia. Véase la sección
       de abajo para algunos ejemplos.
      </para>
     </listitem>
    </varlistentry>   
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;  
  <para>
   Returns this cursor.
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <example>
   <title><function>MongoCursor::batchSize</function> y combinaciones con
    <function>MongoCursor::limit</function></title>
   <programlisting role="php">
<![CDATA[
<?php

// un lote, como mucho 10 elementos. -10 hace que el servidor devuelva 10 elementos,
// y luego elimine el cursor.
$cursor->limit(20)->batchSize(-10);

// primer lote: como mucho 10 elementos
$cursor->limit(10);

// primer lote: como mucho 10 elementos
$cursor->limit(10)->batchSize(20);

// los resultados se obtienen en lotes de 10, con un máximo de 20 elementos
// devueltos (lo que significa dos lotes de 10).
$cursor->limit(20)->batchSize(10);

// los resultados se obtienen en lotes de 7, con un máximo de 30 elementos
// devueltos (lo que significa que el controlador solicita 4 lotes de 7, y
// un lote de 2).
$cursor->limit(30)->batchSize(7)
?>
]]>
   </programlisting>
  </example>
 </refsect1>
 
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   La documentación principal de MongoDB sobre <link xlink:href="&url.mongodb.dochub.batchsize;">límites</link>.
  </para>
  <para>
   <simplelist>
    <member><function>MongoCursor::limit</function></member>
    <member><methodname>MongoCursorInterface::batchSize</methodname></member>
   </simplelist>
  </para>
 </refsect1>
 
 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>1.4.5</entry>
       <entry>
        <para>
         Antes de la versión 1.4.5, este método lanzaba una
         <classname>MongoCursorException</classname> si el cursor ya había
         comenzado a iterar.
        </para>
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 
</refentry>
<!-- 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
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
-->