(PECL mongo >=0.9.0)
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
}
?>
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.
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);
?>
$connection
, string $ns
[, array $query = array()
[, array $fields = array()
]] )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.
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.
Documentación de MongoDB sobre » cursores.