The MongoCursor class

Introduction

A cursor is used to iterate through the results of a database query. For example, to query the database and see all results, you could do:


<?php

$cursor = $collection->find();
var_dump(iterator_to_array($cursor));

?>

You don't generally create cursors using the MongoCursor constructor, you get a new cursor by calling MongoCollection::find() (as shown above).

Suppose that, in the example above, $collection was a 50GB collection. We certainly wouldn't want to load that into memory all at once, which is what a cursor is for: allowing the client to access the collection in dribs and drabs.

If we have a large result set, we can iterate through it, loading a few megabytes of results into memory at a time. For example, we could do:


<?php

$cursor = $collection->find();

foreach ($cursor as $doc) {
    // do something to each document
}

?>

This will go through each document in the collection, loading and garbage collecting documents as needed.

Note that this means that a cursor does not "contain" the database results, it just manages them. Thus, if you print a cursor (with, say, var_dump() or print_r()), you'll just get the cursor object, not your documents. To get the documents themselves, you can use one of the methods shown above.

Cursor Stages

A MongoCursor has two "life stages": pre- and post- query. 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

MongoCursor implements Iterator {

/* Static Fields */

static boolean $slaveOkay = FALSE ;

static integer $timeout = 20000 ;

/* Methods */

public MongoCursor addOption ( string $key , mixed $value )

public MongoCursor batchSize ( int $num )

public __construct ( Mongo $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 bool hasNext ( void )

public MongoCursor hint ( array $key_pattern )

public MongoCursor immortal ([ bool $liveForever = true ] )

public array info ( void )

public string key ( void )

public MongoCursor limit ( int $num )

public void next ( void )

public MongoCursor partial ([ bool $okay = true ] )

public void reset ( void )

public void rewind ( void )

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 )

}

Static Variables

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().
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.

The MongoCursor class

Introduction

Cursor Stages

Class synopsis

Static Variables

See Also

Table of Contents