The MongoCursor class
Introduction
Result object for database query.
A MongoCursor has two "life stages": pre- and post- query. A cursor can be created manually by calling the constructor, but it is most often created by calling MongoCollection::find(). When a cursor is created, it has not yet contacted the database, so it is in its pre-query state. In this state, the client can further specify what they want the query to do, including adding limits, skips, sorts, and more advanced options.
When the client attempts to get a result (by calling MongoCursor::next(), directly or indirectly), the cursor moves into the post-query stage. At this point, the query has been executed by the database and cannot be modified anymore.
<?php
$cursor = $collection->find()->limit(10);
// database has not yet been queried, so more search options can be added
$cursor = $cursor->sort(array("a" => 1));
var_dump($cursor->getNext());
// now database has been queried and more options cannot be added
// so this will throw an exception:
$cursor->skip(4);
?>
Class synopsis
Static Variables
- MongoCursor::slaveOkay
-
If the query should have the "slaveOkay" flag set, which allows reads on the slave (slaves are, by default, just for backup and unreadable). Can be overridden with MongoCursor::slaveOkay().
- MongoCursor::timeout
-
Set timeout in milliseconds for all database responses. To wait forever, use -1. Can be overridden with MongoCursor::timeout(). This does not cause the MongoDB server to cancel the operation, it just causes the driver to stop waiting for a response and throw a MongoCursorTimeoutException.
See Also
MongoDB core docs on » cursors.
Table of Contents
- MongoCursor::addOption — Adds a top-level key/value pair to a query
- MongoCursor::batchSize — Sets the number of results returned per result set
- MongoCursor::__construct — Create a new cursor
- MongoCursor::count — Counts the number of results for this query
- MongoCursor::current — Returns the current element
- MongoCursor::dead — Checks if there are documents that have not been sent yet from the database for this cursor
- MongoCursor::doQuery — Execute the query.
- MongoCursor::explain — Return an explanation of the query, often useful for optimization and debugging
- MongoCursor::fields — Sets the fields for a query
- MongoCursor::getNext — Return the next object to which this cursor points, and advance the cursor
- MongoCursor::hasNext — Checks if there are any more elements in this cursor
- MongoCursor::hint — Gives the database a hint about the query
- MongoCursor::immortal — Sets whether this cursor will timeout
- MongoCursor::info — Gets the query, fields, limit, and skip for this cursor
- MongoCursor::key — Returns the current result's _id
- MongoCursor::limit — Limits the number of results returned
- MongoCursor::next — Advances the cursor to the next result
- MongoCursor::reset — Clears the cursor
- MongoCursor::rewind — Returns the cursor to the beginning of the result set
- MongoCursor::skip — Skips a number of results
- MongoCursor::slaveOkay — Sets whether this query can be done on a slave
- MongoCursor::snapshot — Use snapshot mode for the query
- MongoCursor::sort — Sorts the results by given fields
- MongoCursor::tailable — Sets whether this cursor will be left open after fetching the last results
- MongoCursor::timeout — Sets a client-side timeout for this query
- MongoCursor::valid — Checks if the cursor is reading a valid result.