(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
bool
$slaveOkay
= false
static
int
$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 ( ) : array
public dead ( ) : bool
protected doQuery ( ) : void
public explain ( ) : array
public fields
( array $f
) : MongoCursor
public getNext ( ) : array
public getReadPreference ( ) : array
public hasNext ( ) : bool
public hint
( mixed $index
) : MongoCursor
public immortal
([ bool $liveForever = true
] ) : MongoCursor
public info ( ) : array
public key ( ) : string|int
public limit
( int $num
) : MongoCursor
public maxTimeMS
( int $ms
) : MongoCursor
public next ( ) : array
public partial
([ bool $okay = true
] ) : MongoCursor
public reset ( ) : void
public rewind ( ) : 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 ( ) : MongoCursor
public sort
( array $fields
) : MongoCursor
public tailable
([ bool $tail = true
] ) : MongoCursor
public timeout
( int $ms
) : MongoCursor
public valid ( ) : bool
}
静的変数
slaveOkayクエリに "slaveOkay" フラグが設定されていると、セカンダリ側での読み込みを許可します (セカンダリは、デフォルトでは単なるバックアップ用であり読み込みはできません)。 MongoCursor::slaveOkay() で上書きすることができます。
この機能は 非推奨 です。かわりに 優先読み込み を使いましょう。
timeoutデータベースからのすべての応答に対するタイムアウトをミリ秒単位で設定します。 ずっと待ち続ける場合は
-1を指定します。 MongoCursor::timeout() で上書きすることができます。 これは MongoDB サーバーに対する操作をキャンセルするわけではなく、 単にドライバ側で応答を待つのをやめて MongoCursorTimeoutException をスローするだけです。
目次
- MongoCursor::addOption — トップレベルの キー/値 のペアをクエリに追加する
- MongoCursor::awaitData — Sets whether this cursor will wait for a while for a tailable cursor to return more data
- MongoCursor::batchSize — Limits the number of elements returned in one batch
- MongoCursor::__construct — 新しいカーソルを作成する
- MongoCursor::count — このクエリの結果の数を数える
- MongoCursor::current — 現在の要素を返す
- MongoCursor::dead — まだデータベースから送信されていないドキュメントがあるかどうかを調べる
- MongoCursor::doQuery — Execute the query
- MongoCursor::explain — 最適化やデバッグの際に有効な、クエリの explain を返す
- MongoCursor::fields — クエリのフィールドを設定する
- MongoCursor::getNext — カーソルを次の結果に進めてその結果を返す
- MongoCursor::getReadPreference — このクエリの優先読み込みを取得する
- MongoCursor::hasNext — このカーソルにまだ要素があるかどうかを調べる
- MongoCursor::hint — クエリについてのヒントをデータベースに与える
- MongoCursor::immortal — Sets whether this cursor will timeout
- MongoCursor::info — カーソルの作成と走査に関する情報を取得する
- MongoCursor::key — 現在の結果の _id、あるいは結果セット内のインデックスを返す
- MongoCursor::limit — 返す結果の数を制限する
- MongoCursor::maxTimeMS — Sets a server-side timeout for this query
- MongoCursor::next — カーソルを次の結果に進めてその結果を返す
- MongoCursor::partial — If this query should fetch partial results from mongos if a shard is down
- MongoCursor::reset — カーソルを消去する
- MongoCursor::rewind — カーソルを結果セットの先頭に戻す
- MongoCursor::setFlag — Sets arbitrary flags in case there is no method available the specific flag
- MongoCursor::setReadPreference — このクエリの優先読み込みを設定する
- MongoCursor::skip — 結果をスキップする
- MongoCursor::slaveOkay — Sets whether this query can be done on a secondary [deprecated]
- MongoCursor::snapshot — このクエリでスナップショットモードを使う
- MongoCursor::sort — 指定したフィールドで結果をソートする
- MongoCursor::tailable — Sets whether this cursor will be left open after fetching the last results
- MongoCursor::timeout — このクエリのクライアント側のタイムアウトを設定する
- MongoCursor::valid — Checks if the cursor is reading a valid result
/* 静的フィールド */