Edit Report a Bug

    MongoCursor クラス

    (PECL mongo >=0.9.0)

    はじめに

    カーソルは、データベースクエリの結果を反復処理するときに使います。 たとえば、データベースに問い合わせたすべての結果を見るには次のようにします。

    例1 MongoCursor の基本的な使いかた

    <?php

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

    ?>

    一般に、カーソルを作るときに MongoCursor のコンストラクタを使うことはありません。 新しいカーソルを作るには、(上の例のように) MongoCollection::find() をコールします。

    上の例で、仮に $collection が 50GB のコレクションだったとしましょう。そんなときに、 結果をすべて一度にメモリに読み込もうとは思わないでしょう。 そんなときのためにカーソルが存在します。 カーソルを使えば、クライアント側から少しずつコレクションにアクセスできるのです。

    結果セットが大規模になっても、それを反復処理して 一度にメモリに取り込むデータ量を数メガバイト程度にすることができます。 たとえばこのようにします。

    例2 MongoCursor の反復処理

    <?php

    $cursor     = $collection->find();

    foreach (    $cursor as $doc) {
            // ここで各ドキュメントについて何らかの処理をします
    }

    ?>
    これはコレクション内の各ドキュメントを順にたどり、 必要に応じてドキュメントの読み込みやガベージコレクションを行います。

    カーソルにデータベースの結果が "含まれている" わけではないことに注意しましょう。 カーソルは単に結果を管理するだけのものです。つまり、 (var_dump() や print_r() で) カーソルの内容を出力してもドキュメントは見えません。 単にカーソルオブジェクトが表示されるだけです。 ドキュメント自身を取得するには、上のメソッドのいずれかを使います。

    カーソルのステージ

    MongoCursor には二段階の「ライフステージ」があります。 クエリ前とクエリ後です。 カーソルを作った時点ではまだデータベースに接続していません。 つまり、クエリ前の段階です。この段階では、クエリに何をしてほしいのかをさらに指定することができます。 取得数の制限や読み飛ばし、ソートなどのオプションを指定できるのです。

    クライアントが結果を取得しようとする (直接的あるいは間接的に MongoCursor::next() をコールする) と、 そのカーソルはクエリ後の段階に進みます。

    例3 MongoCursor へのオプションの追加

    <?php

    $cursor     = $collection->find()->limit(10);

    // まだデータベースへの問い合わせは行われていないので、検索オプションをさらに追加することができます
    $cursor = $cursor->sort(array("a" => 1));

    var_dump($cursor->getNext());
    // ここでデータベースへの問い合わせが行われるので、これ以降はオプションを追加することはできません

    // つまり、これは例外をスローします
    $cursor->skip(4);
    ?>

    クラス概要

    MongoCursor implements MongoCursorInterface , Iterator {
    /* 静的フィールド */
    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
    }

    静的変数

    slaveOkay

    クエリに "slaveOkay" フラグが設定されていると、セカンダリ側での読み込みを許可します (セカンダリは、デフォルトでは単なるバックアップ用であり読み込みはできません)。 MongoCursor::slaveOkay() で上書きすることができます。

    この機能は 非推奨 です。かわりに 優先読み込み を使いましょう。

    timeout

    データベースからのすべての応答に対するタイムアウトをミリ秒単位で設定します。 ずっと待ち続ける場合は -1 を指定します。 MongoCursor::timeout() で上書きすることができます。 これは MongoDB サーバーに対する操作をキャンセルするわけではなく、 単にドライバ側で応答を待つのをやめて MongoCursorTimeoutException をスローするだけです。

    参考

    MongoDB コアドキュメントの » カーソル を参照ください。

    目次

    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