Edit Report a Bug

    The MongoCursor class

    (PECL mongo >=0.9.0)

    简介

    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:

    Example #1 MongoCursor basic usage

    <?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:

    Example #2 Iterating over MongoCursor

    <?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.

    Example #3 Adding options to MongoCursor

    <?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);
    ?>

    类摘要

    MongoCursor implements MongoCursorInterface , Iterator {
    /* Static Fields */
    static boolean slaveOkay = FALSE ;
    static integer timeout = 30000 ;
    /* 方法 */
    public addOption ( string $key , mixed $value ) : MongoCursor
    public awaitData ([ bool $wait = TRUE ] ) : MongoCursor
    public batchSize ( int $batchSize ) : MongoCursor
    public __construct ( MongoClient $connection , string $ns [, array $query = array() [, array $fields = array() ]] )
    public count ([ bool $foundOnly = FALSE ] ) : int
    public current ( void ) : array
    public dead ( void ) : bool
    protected doQuery ( void ) : void
    public explain ( void ) : array
    public fields ( array $f ) : MongoCursor
    public getNext ( void ) : array
    public getReadPreference ( void ) : array
    public hasNext ( void ) : bool
    public hint ( mixed $index ) : MongoCursor
    public immortal ([ bool $liveForever = TRUE ] ) : MongoCursor
    public info ( void ) : array
    public key ( void ) : string|int
    public limit ( int $num ) : MongoCursor
    public maxTimeMS ( int $ms ) : MongoCursor
    public next ( void ) : array
    public partial ([ bool $okay = TRUE ] ) : MongoCursor
    public reset ( void ) : void
    public rewind ( void ) : void
    public setFlag ( int $flag [, bool $set = TRUE ] ) : MongoCursor
    public setReadPreference ( string $read_preference [, array $tags ] ) : MongoCursor
    public skip ( int $num ) : MongoCursor
    public slaveOkay ([ bool $okay = TRUE ] ) : MongoCursor
    public snapshot ( void ) : MongoCursor
    public sort ( array $fields ) : MongoCursor
    public tailable ([ bool $tail = TRUE ] ) : MongoCursor
    public timeout ( int $ms ) : MongoCursor
    public valid ( void ) : bool
    }

    Static Variables

    slaveOkay

    If the query should have the "slaveOkay" flag set, which allows reads on the secondary (secondaries are, by default, just for backup and not queried). Can be overridden with MongoCursor::slaveOkay().

    This functionality is deprecated. Please use 读取首选项 instead.

    timeout

    Set timeout in milliseconds for all database responses. Use -1 to wait forever. Can be overridden with MongoCursor::timeout(). This does not cause the MongoDB server to cancel the operation; it only instructs the driver to stop waiting for a response and throw a MongoCursorTimeoutException after a set time.

    参见

    MongoDB core docs on » cursors.

    Table of Contents

    add a note add a note

    User Contributed Notes 4 notes

    up
    9
    adrian dot zurek at netmedia dot com dot pl
    13 years ago
    One *VERY* important note, if You do:
    $cursor = $collection->find(array(), array('_id' => 0)); // ommit '_id' field in result

    then:
    var_dump(iterator_to_array($cursor));

    will return only *ONE* document, not all!
    up
    2
    alex
    7 years ago
    Deprecated:
    $cursor = $collection->find();
    $cursor->limit(1);

    Use instead:
    $collection->find([], [ 'limit' => 1 ]);
    up
    1
    Adil Baig @ AiDezigns
    13 years ago
    If you want to know whether a cursor returned any results it is faster to use 'hasNext()' than 'count'
    up
    0
    Adil Baig
    9 years ago
    The documentation says $timeout is a static variable that can be set:

    "Set timeout in milliseconds for all database responses."

    This feature has been deprecated. Attempting to set it will result in a warning :

    "PHP Deprecated:  MongoCollection::find(): The 'MongoCursor::$timeout' static property is deprecated, please call MongoCursor->timeout() instead"
    add a note add a note
    To Top