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 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|int key ( void )

public MongoCursor limit ( int $num )

public MongoCursor maxTimeMS ( int $ms )

public array 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 コアドキュメントの » カーソルを参照ください。

MongoCursor::addOption ? トップレベルのキー/値のペアをクエリに追加する
MongoCursor::awaitData ? 追尾可能なカーソルで、データがないときにしばらく待つかどうかを設定する
MongoCursor::batchSize ? ひとつのバッチで返す要素数を制限する
MongoCursor::__construct ? 新しいカーソルを作成する
MongoCursor::count ? このクエリの結果の数を数える
MongoCursor::current ? 現在の要素を返す
MongoCursor::dead ? まだデータベースから送信されていないドキュメントがあるかどうかを調べる
MongoCursor::doQuery ? クエリを実行する
MongoCursor::explain ? 最適化やデバッグの際に有効な、クエリの explain を返す
MongoCursor::fields ? クエリのフィールドを設定する
MongoCursor::getNext ? カーソルを次の結果に進めてその結果を返す
MongoCursor::getReadPreference ? このクエリの優先読み込みを取得する
MongoCursor::hasNext ? このカーソルにまだ要素があるかどうかを調べる
MongoCursor::hint ? クエリについてのヒントをデータベースに与える
MongoCursor::immortal ? このカーソルをタイムアウトさせるかどうかを設定する
MongoCursor::info ? カーソルの作成と走査に関する情報を取得する
MongoCursor::key ? 現在の結果の _id、あるいは結果セット内のインデックスを返す
MongoCursor::limit ? 返す結果の数を制限する
MongoCursor::maxTimeMS ? Sets a server-side timeout for this query
MongoCursor::next ? カーソルを次の結果に進めてその結果を返す
MongoCursor::partial ? シャードがダウンしているときにこのクエリが mongos から部分的な結果を返すようにするかどうか
MongoCursor::reset ? カーソルを消去する
MongoCursor::rewind ? カーソルを結果セットの先頭に戻す
MongoCursor::setFlag ? 専用のメソッドが存在しない任意のフラグを設定する
MongoCursor::setReadPreference ? このクエリの優先読み込みを設定する
MongoCursor::skip ? 結果をスキップする
MongoCursor::slaveOkay ? このクエリをセカンダリ上で完了できるかどうかを設定する [非推奨]
MongoCursor::snapshot ? このクエリでスナップショットモードを使う
MongoCursor::sort ? 指定したフィールドで結果をソートする
MongoCursor::tailable ? このカーソルが、最後の結果を取得した後もオープンしたままにしておくかどうかを設定する
MongoCursor::timeout ? このクエリのクライアント側のタイムアウトを設定する
MongoCursor::valid ? カーソルが正しい結果を読んでいるかどうかを調べる

各種マニュアル： PHPマニュアル \| PEARマニュアル \| Smarty(英語)マニュアル \| PHP-GTKマニュアル \| 「MongoCursor クラス」をGoogle検索
copyright © 1997-2024 PHP ドキュメント作成グループ(ライセンス). provided by php spot.	マニュアル：

MongoCursor クラス

はじめに

カーソルのステージ

クラス概要

静的変数

参考

目次