La clase MongoCursor

(PECL mongo >=0.9.0)

Introducción

Un cursor se utiliza parar recorrer el resultado de una consulta a la base de datos. Por ejemplo, para consultar la base de datos y revisar los resultados, se podría hacer lo siguiente:

Ejemplo #1 Uso básico de MongoCursor


<?php

$cursor = $collection->find();
var_dump(iterator_to_array($cursor));

?>

Por norma general, los cursores no se crean utilizando el constructor MongoCursor, ya que se obtienen al invicar a MongoCollection::find() (como en el ejemplo superior).

Supóngase que, en el ejemplo superior, $collection fuera una colección de 50GB. No quisiéramos tener que alojar en memoria todo de una vez, y esto es lo que solucionan los cursores: permiten al cliente acceder a la colección gota a gota.

Si tuviéramos un resultado extenso, podríamos recorrerlo cargando unos pocos megabytes a memoria cada vez. Por ejemplo:

Ejemplo #2 Iterar sobre MongoCursor


<?php

$cursor = $collection->find();

foreach ($cursor as $doc) {
    // hacer algo a cada documento
}

?>

Esto recorrerá cada documento de la colección, cargando y eliminando de memoria cada documento según se necesite.

Debe tenerse en cuenta que esto significa que un cursor no "contiene" el resultado de la base de datos, sino que sólo lo gestiona. Por tanto, si se imprimiera un cursor (con, digamos, var_dump() o print_r()), sólo se obtendría el propio objeto cursor, sin los documentos. Para obtener los documentos en sí, debe utilizarse alguno de los métodos vistos arriba.

Estados de un Cursor

Un MongoCursor tiene dos estados: pre y post consulta. Al crear un cursor, éste no se conecta a la base de datos, por lo que está en estado pre-consulta. En este estado, el cliente puede indicar qué quiere consultar, definiendo límites, saltos, ordenaciones y más opciones avanzadas.

Cuando el cliente solicita el resultado (invocando MongoCursor::next(), directa o indirectamente), el cursor avanza al estado post-consulta. En este punto, la consulta ya se ha ejecutado por la base de datos y ya no se puede modificar.

Ejemplo #3 Añadir opciones a MongoCursor


<?php

$cursor = $collection->find()->limit(10);

// todavía no se ha consultado la base de datos, de modo que se pueden añadir más opciones
$cursor = $cursor->sort(array("a" => 1));

var_dump($cursor->getNext());
// ya se ha consultado la base de datos, y no se pueden añadir más opciones

// por lo que esto lanzaría una excepción:
$cursor->skip(4);
?>

Sinopsis de la Clase

MongoCursor implements MongoCursorInterface , Iterator {

/* Campos Estáticos */

static boolean $slaveOkay = FALSE ;

static integer $timeout = 30000 ;

/* Métodos */

public addOption ( string $key , mixed $value ) : MongoCursor

public awaitData ([ bool $wait = true ] ) : MongoCursor

public batchSize ( int $batchSize ) : MongoCursor

public __construct ( MongoClient $connection , string $ns [, array $query = array() [, array $fields = array() ]] )

public count ([ bool $foundOnly = FALSE ] ) : int

public current ( void ) : array

public dead ( void ) : bool

protected doQuery ( void ) : void

public explain ( void ) : array

public fields ( array $f ) : MongoCursor

public getNext ( void ) : array

public getReadPreference ( void ) : array

public hasNext ( void ) : bool

public hint ( mixed $index ) : MongoCursor

public immortal ([ bool $liveForever = true ] ) : MongoCursor

public info ( void ) : array

public key ( void ) : string|int

public limit ( int $num ) : MongoCursor

public maxTimeMS ( int $ms ) : MongoCursor

public next ( void ) : array

public partial ([ bool $okay = true ] ) : MongoCursor

public reset ( void ) : void

public rewind ( void ) : void

public setFlag ( int $flag [, bool $set = true ] ) : MongoCursor

public setReadPreference ( string $read_preference [, array $tags ] ) : MongoCursor

public skip ( int $num ) : MongoCursor

public slaveOkay ([ bool $okay = true ] ) : MongoCursor

public snapshot ( void ) : MongoCursor

public sort ( array $fields ) : MongoCursor

public tailable ([ bool $tail = true ] ) : MongoCursor

public timeout ( int $ms ) : MongoCursor

public valid ( void ) : bool

}

Variables Estáticas

slaveOkay

Si la consulta debe o no tener asignada la bandera "slaveOkay", la cual permite leer el secundario (por omisión, los secundarios son para hacer copias de seguridad, no consultas). Puede sobrescribirse con MongoCursor::slaveOkay().

Esta funcionalidad es obsoleta. Por favor, use Preferencias de lectura en su lugar.

timeout

Establecer el tiempo de espera en milisegundos para las respuestas de todas las bases de datos. Use -1 para esperar eternamente. Se puede sobcrescribir con MongoCursor::timeout(). Esto no hace que el servidor de MongoDB cancele la operación; sólo hace que el controlador deje de esperar una respuesta y lanza una MongoCursorTimeoutException después de un tiempo establecido.

Ver también

Documentación de MongoDB sobre » cursores.

Tabla de contenidos

MongoCursor::addOption — Añade un par clave/valor de alto nivel a una consulta
MongoCursor::awaitData — Establece si el cursor esperará un momento a que un cursor de seguimiento devuelva más datos
MongoCursor::batchSize — Limita el número de elementos devueltos en un lote
MongoCursor::__construct — Crea un nuevo cursor
MongoCursor::count — Cuenta el número de resultados de esta consulta
MongoCursor::current — Devuelve el elemento actual
MongoCursor::dead — Comprueba si hay resultados que no han sido enviados aún de la base de datos
MongoCursor::doQuery — Ejecutar un sentencia
MongoCursor::explain — Devuelve una explicación de la consulta, útil para la optimización y depuración
MongoCursor::fields — Establece los campos para una consulta
MongoCursor::getNext — Avanza el cursor al siguiente resultado y devuelve dicho resultado
MongoCursor::getReadPreference — Obtener la preferencia de lectura para esta consulta
MongoCursor::hasNext — Comprueba si existe algún elemento más en este cursor
MongoCursor::hint — Da a la base de datos un indicio sobre la consulta
MongoCursor::immortal — Establece si este cursor expirará
MongoCursor::info — Obtiene la información sobre la creación e iteración del cursor
MongoCursor::key — Devuelve el _id del resultado actual, o su índice dentro del conjunto de resultados
MongoCursor::limit — Limita el número de resultados devueltos
MongoCursor::maxTimeMS — Establece un tiempo límite en el lado del cliente para esta consulta
MongoCursor::next — Avanza el cursor al siguiente resultado, y devuelve dicho resultado
MongoCursor::partial — Si esta consulta debería obtener resultados parciales de mongos si un trozo ha caído
MongoCursor::reset — Limpia el cursor
MongoCursor::rewind — Devuelve el cursor al inicio del conjunto de resultados
MongoCursor::setFlag — Establece banderas arbitrarias en caso de que no haya métodos disponibles para una bandera específica
MongoCursor::setReadPreference — Establece la preferencia de lectura para esta consulta
MongoCursor::skip — Omite un número de resultados
MongoCursor::slaveOkay — Establece si esta consulta puede realizarse en un secundario [obsoleto]
MongoCursor::snapshot — Usar el modo 'snapshot' para la consulta
MongoCursor::sort — Ordena los resultados por el campo que se indique
MongoCursor::tailable — Establece si este cursor se dejará abierto después de obtener los últimos resultados
MongoCursor::timeout — Establece un tiempo de espera en el lado del cliente para esta consulta
MongoCursor::valid — Comprueba si el cursor está leyendo un resultado válido

add a note

User Contributed Notes 4 notes

down

adrian dot zurek at netmedia dot com dot pl ¶

13 years ago


One *VERY* important note, if You do:
$cursor = $collection->find(array(), array('_id' => 0)); // ommit '_id' field in result 

then:
var_dump(iterator_to_array($cursor));

will return only *ONE* document, not all!

down

alex ¶

7 years ago


Deprecated:
$cursor = $collection->find();
$cursor->limit(1);

Use instead:
$collection->find([], [ 'limit' => 1 ]);

down

Adil Baig @ AiDezigns ¶

13 years ago


If you want to know whether a cursor returned any results it is faster to use 'hasNext()' than 'count'

down

Adil Baig ¶

9 years ago


The documentation says $timeout is a static variable that can be set:

"Set timeout in milliseconds for all database responses."

This feature has been deprecated. Attempting to set it will result in a warning :

"PHP Deprecated:  MongoCollection::find(): The 'MongoCursor::$timeout' static property is deprecated, please call MongoCursor->timeout() instead"

add a note