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));

?>