(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);
?>
$connection
, string $ns
[, array $query
= array()
[, array $fields
= array()
]] )クエリに "slaveOkay" フラグが設定されていると、セカンダリ側での読み込みを許可します (セカンダリは、デフォルトでは単なるバックアップ用であり読み込みはできません)。 MongoCursor::slaveOkay() で上書きすることができます。
この機能は 非推奨 です。かわりに 優先読み込み を使いましょう。
データベースからのすべての応答に対するタイムアウトをミリ秒単位で設定します。 ずっと待ち続ける場合は -1 を指定します。 MongoCursor::timeout() で上書きすることができます。 これは MongoDB サーバーに対する操作をキャンセルするわけではなく、 単にドライバ側で応答を待つのをやめて MongoCursorTimeoutException をスローするだけです。
MongoDB コアドキュメントの » カーソル を参照ください。