コアクラス群
PHP Manual

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 Iterator {
/* 静的フィールド */
static boolean $slaveOkay = FALSE ;
static integer $timeout = 30000 ;
/* メソッド */
public MongoCursor addOption ( string $key , mixed $value )
public MongoCursor awaitData ([ bool $wait = true ] )
public MongoCursor batchSize ( int $batchSize )
public __construct ( MongoClient $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 array getReadPreference ( void )
public bool hasNext ( void )
public MongoCursor hint ( mixed $index )
public MongoCursor immortal ([ bool $liveForever = true ] )
public array info ( void )
public string key ( void )
public MongoCursor limit ( int $num )
public MongoCursor maxTimeMS ( int $ms )
public void next ( void )
public MongoCursor partial ([ bool $okay = true ] )
public void reset ( void )
public void rewind ( void )
public MongoCursor setFlag ( int $flag [, bool $set = true ] )
public MongoCursor setReadPreference ( string $read_preference [, array $tags ] )
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 )
}

静的変数

slaveOkay

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

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

timeout

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

参考

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

目次

コアクラス群
PHP Manual