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