ドキュメントを更新して返す

説明

public array MongoCollection::findAndModify ( array $query [, array $update [, array $fields [, array $options ]]] )

findAndModify コマンドは、単一のドキュメントをアトミックに変更して返します。デフォルトでは、返されるドキュメントには、この更新による変更内容が含まれません。更新で変更した結果のドキュメントを返すには、new オプションを使います。

パラメータ

query

クエリの検索条件。

update

更新条件。

fields

オプションで、返すフィールドを絞り込めます。

options

適用するオプションの配列。マッチしたドキュメントを DB から削除してから返すなどのオプションを指定できます。

オプション	説明
`sort` array	クエリが複数のドキュメントを選択したときに、どのドキュメントを変更するかを決めます。 findAndModify が変更するのは、この引数で指定した並び順で最初にあるドキュメントだけです。
`remove` boolean	`update` フィールドが存在するときは必須ではありません。 `TRUE` にすると、選択したドキュメントを削除します。デフォルトは `FALSE` です。
`update` array	`remove` フィールドが存在するときは必須ではありません。選択したドキュメントを更新します。
`new` boolean	必須ではありません。`TRUE` にすると、変更前のドキュメントではなく変更後のドキュメントを返します。 findAndModify メソッドは、remove 操作のときには `new` オプションを無視します。デフォルトは `FALSE` です。
`upsert` boolean	必須ではありません。`update` と組み合わせて使います。 `TRUE` にすると、クエリがドキュメントを返さないときに findAndModify コマンドが新しいドキュメントを作ります。デフォルトは `FALSE` です。MongoDB 2.2 では、upsert が `TRUE` のときに findAndModify コマンドは `NULL` を返します。

返り値

元のドキュメントを返します。 new が設定されている場合は変更後のドキュメントを返します。

エラー / 例外

失敗した場合に MongoResultException をスローします。

例

例1 MongoCollection::findAndModify() の例


<?php
$m = new Mongo;
$col = $m->selectDB("test")->jobs;

$col->insert(array(
     "name" => "Next promo",
     "inprogress" => false,
     "priority" => 0,
     "tasks" => array( "select product", "add inventory", "do placement"),
) );

$col->insert(array(
     "name" => "Biz report",
     "inprogress" => false,
     "priority" => 1,
     "tasks" => array( "run sales report", "email report" )
) );

$col->insert(array(
     "name" => "Biz report",
     "inprogress" => false,
     "priority" => 2,
     "tasks" => array( "run marketing report", "email report" )
    ),
    array("w" => 1)
);



$retval = $col->findAndModify(
     array("inprogress" => false, "name" => "Biz report"),
     array('$set' => array('inprogress' => true, "started" => new MongoDate())),
     null,
     array(
        "sort" => array("priority" => -1),
        "new" => true,
    )
);

var_dump($retval);
?>

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

array(6) {
  ["_id"]=>
  object(MongoId)#7 (1) {
    ["$id"]=>
    string(24) "5091b5b244415e8cc3000002"
  }
  ["inprogress"]=>
  bool(true)
  ["name"]=>
  string(10) "Biz report"
  ["priority"]=>
  int(2)
  ["started"]=>
  object(MongoDate)#8 (2) {
    ["sec"]=>
    int(1351726514)
    ["usec"]=>
    int(925000)
  }
  ["tasks"]=>
  array(2) {
    [0]=>
    string(20) "run marketing report"
    [1]=>
    string(12) "email report"
  }
}

例2 MongoCollection::findAndModify() のエラー処理


<?php
$m = new Mongo;
$col = $m->selectDB("test")->jobs;
try {
    $retval = $col->findAndModify(
         array("inprogress" => false, "name" => "Next promo"),
         array('$pop' => array("tasks" => -1)),
         array("tasks" => array('$pop' => array("stuff"))),
         array("new" => true)
    );
} catch(MongoResultException $e) {
    echo $e->getCode(), " : ", $e->getMessage(), "\n";
    var_dump($e->getDocument());
}

?>

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

13097 : exception: Unsupported projection option: $pop
array(3) {
  ["errmsg"]=>
  string(46) "exception: Unsupported projection option: $pop"
  ["code"]=>
  int(13097)
  ["ok"]=>
  float(0)
}

参考

MongoDB の » findAndModify コマンドのドキュメント