MongoCursor
PHP Manual

MongoCursor::addOption

(PECL mongo >=1.0.4)

MongoCursor::addOption — トップレベルの キー/値 のペアをクエリに追加する

説明

public MongoCursor MongoCursor::addOption ( string $key , mixed $value )

これは高度な関数なので、今何をしているのかをわかっている人以外は使ってはいけません。

ソートやヒントなどの他のオプションを指定する場合は、クエリを "query" フィールドに書くこともできます。 たとえばソートを追加した場合は、 クエリは次のようにサブフィールドのひとつとなります。

<?php

$query = array("query" => $query, "orderby" => $sort);

?>

このメソッドは、トップレベルのフィールドをクエリに追加します。 クエリにサブオブジェクトを作成 (まだ存在しない場合) し、 指定した キー/値 のペアをトップレベルに追加します。

警告

クエリにその場で条件を追加するという目的で使うことはできません。たとえば、 これは正しく動作しません。

<?php

// 間違った使いかた
$cursor = $users->find()->addOption("name", "joe")->addOption("age", 20);

?>
これは、名前が "joe" で 20 才のユーザーを捜すというクエリには なりません。

パラメータ

key

追加したいフィールド名。

value

追加したい値。

返り値

このカーソルを返します。

エラー / 例外

カーソルの反復処理が始まっている場合は MongoCursorException をスローします。

例

例1 MongoCursor::addOption() によるコメントの追加の例

MongoDB は、サーバーに送る特別なオプションをサポートしています。 シェルの _addSpecial オプションを使うと、 $comment をサーバーに送信します。 このコメントは、プロファイリングログ (遅いクエリのログなど) に表示されます。 PHP ドライバでは、 MongoCursor::addOption() メソッドを利用します。

<?php
$m = new MongoClient;
$c = $m->demo->demo;
$cursor = $c->find();
$cursor->addOption('$comment', "This comment will show up in the profiling log");

foreach ($cursor as $document) { /* empty */ }
?>

上の例の出力は、 たとえば以下のようになります。

{
    "op" : "query",
    "ns" : "demo.demo",
    "query" : {
        "$query" : {
             
        },
        "$comment" : "This comment will show up in the profiling log"
    },
    "cursorid" : 168463566447,
    "ntoreturn" : 0,
    "ntoskip" : 0,
    "nscanned" : 101,
    "nscannedObjects" : 101,
    "keyUpdates" : 0,
    "numYield" : 0,
…

例2 MongoCursor::addOption() の例

MongoCursor::skip() を使って何百万件もの結果をスキップすると、 処理速度が低下します。これを回避する方法のひとつが、クエリのオプション $min あるいは $max を使うことです。 これらは便利ですが、検索するフィールドにインデックスがなければなりません。 この例は、$min を MongoCursor::skip() の代替として使う方法を示します。

<?php

// インデックスがなければなりません
$c->ensureIndex(array("ts" => 1));

// マシンの性能によって、この値を適宜変更しなければならないかもしれません
// (性能の良いマシンで 30 秒ほどかかります)
for ($i = 0; $i < 30000000; $i++) {
    $c->insert(array("ts" => new MongoDate(), "i" => $i));
}

$now = strtotime("now");

// 最後の 2 秒で追加されたドキュメントを探します
$cursor = $c->find()->addOption('$min', array("ts" => $now-2));

?>
MongoCursor
PHP Manual