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:

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 Iterator {
/* Campos Estáticos */
static boolean $slaveOkay = FALSE ;
static integer $timeout = 30000 ;
/* Métodos */
public MongoCursor addOption ( string $key , mixed $value )
public MongoCursor awaitData ([ bool $wait = true ] )
public MongoCursor batchSize ( int $batchSize )
public __construct ( MongoClient $connection , string $ns [, array $query = array() [, array $fields = array() ]] )
public int count ([ bool $foundOnly = FALSE ] )
public array current ( void )
public bool dead ( void )
protected void doQuery ( void )
public array explain ( void )
public MongoCursor fields ( array $f )
public array getNext ( void )
public array getReadPreference ( void )
public bool hasNext ( void )
public MongoCursor hint ( mixed $index )
public MongoCursor immortal ([ bool $liveForever = true ] )
public array info ( void )
public string key ( void )
public MongoCursor limit ( int $num )
public MongoCursor maxTimeMS ( int $ms )
public void next ( void )
public MongoCursor partial ([ bool $okay = true ] )
public void reset ( void )
public void rewind ( void )
public MongoCursor setFlag ( int $flag [, bool $set = true ] )
public MongoCursor setReadPreference ( string $read_preference [, array $tags ] )
public MongoCursor skip ( int $num )
public MongoCursor slaveOkay ([ bool $okay = true ] )
public MongoCursor snapshot ( void )
public MongoCursor sort ( array $fields )
public MongoCursor tailable ([ bool $tail = true ] )
public MongoCursor timeout ( int $ms )
public bool valid ( void )
}

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