(No hay información de versión disponible, podría estar únicamente en SVN)
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:
<?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:
<?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.
<?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 en un esclavo (por omisión, los esclavos son para hacer copias de seguridad). Puede sobrescribirse con MongoCursor::slaveOkay().
Establecer el tiempo de espera en milisegundos para las respuestas de todas las bases de datos. Para esperar eternamente, use -1. Se puede sobcrescribir con MongoCursor::timeout(). Esto no hace que el servidor MongoDB cancele la operación; sólo hace que el driver deje de esperar, y emite una excepción MongoCursorTimeoutException.
Documentación de MongoDB sobre » cursores.