MongoCollection::save
(PECL mongo >=0.9.0)
MongoCollection::save — ドキュメントをコレクションに保存する
説明
データベースから取得したオブジェクトの場合はデータベース上の既存のオブジェクトを更新し、 それ以外の場合はオブジェクトを追加します。
パラメータ
-
document -
保存したい配列あるいはオブジェクト。オブジェクトを使う場合は、 protected や private のプロパティは保持できません。
注意:
_id のキーあるいはプロパティを持たない場合は、 新しい MongoId インスタンスを作ってそれを代入します。 この挙動に関する詳しい情報は MongoCollection::insert() を参照ください。
-
options -
保存時のオプション。
"fsync"
Boolean 型で、デフォルトは
FALSEです。 ジャーナリングが有効な場合、これは "j" とまったく同じ動きをします。 ジャーナリングが有効でない場合は、追加をディスク上のデータベースファイルに同期させるまで成功したと見なさないようになります。TRUEにすると確認つき書き込みが暗黙のうちに設定され、"w" の値を 0 にします。注意: ジャーナリングが有効な場合は、"fsync" のかわりに "j" を使いましょう。 "fsync" と "j" を同時に指定すると、エラーになります。
"j"
デフォルトは
FALSEです。これを指定すると、追加をジャーナルに同期させるまで成功したと見なさないようになります。TRUEにすると確認付き書き込みと見なされ、"w" の設定を 0 に上書きします。注意: このオプションを使っているときにジャーナリングを無効にすると、MongoDB 2.6 以降ではエラーが発生して書き込みに失敗します。古いバージョンのサーバーでは、単純にオプションの指定を無視します。
"socketTimeoutMS"
このオプションは、ソケット通信の制限時間を、ミリ秒単位で指定します。この時間内にサーバーからの反応がなければ、MongoCursorTimeoutException をスローします。この場合、サーバー側で書き込み処理が行われたのかどうかを判断できなくなります。-1 を指定すると、永遠にブロックします。MongoClient のデフォルト値は 30000 (30 秒) です。
-
"w"
WriteConcerns を参照ください。MongoClient でのデフォルト値は 1 です。
"wtimeout"
廃止予定。"wTimeoutMS" のエイリアスです。
"wTimeoutMS"
このオプションは、書き込み確認を待つ制限時間をミリ秒単位で指定します。これが書き込み操作に適用されるのは、"w" が 1 より大きい場合のみです。というのも、タイムアウトはレプリケーションに関する機能だからです。この時間内に書き込み確認ができなかった場合は MongoCursorException をスローします。0 を指定すると、永遠にブロックし続けます。MongoClient でのデフォルトは 10000 ミリ秒 (10 秒) です。
"safe"
非推奨。write concern の w オプションを使いましょう。
"timeout"
非推奨。"socketTimeoutMS" のエイリアス。
返り値
w が設定されている場合は、
保存結果を含む配列を返します。設定されていない場合は、
配列が空でなかったかどうかをあらわす boolean 値を返します (空の配列は追加されません)。
エラー / 例外
追加したドキュメントが空だったり長さがゼロのキーが含まれていたりした場合に MongoException をスローします。 protected や private なプロパティを持つオブジェクトを追加しようとすると、 キーの長さがゼロのエラーを引き起こします。
"w" オプションが設定されていて書き込みが失敗した場合に MongoCursorException をスローします。
"w" オプションの値が 1 より大きく設定されていて、操作の完了までの時間が MongoCursor::$timeout ミリ秒をこえた場合に MongoCursorTimeoutException をスローします。サーバー上での操作は止めません。これはクライアント側でのタイムアウトです。MongoCollection::$wtimeout はミリ秒です。
変更履歴
| バージョン | 説明 |
|---|---|
| 1.5.0 |
オプション "wTimeoutMS" が追加されました。
これは "wtimeout" を置き換えるものです。
"wtimeout" を使うと、
オプション "socketTimeoutMS" が追加されました。
これは "timeout" を置き換えるものです。
"timeout" を使うと、
"safe" を使うと、 |
| 1.2.0 | "timeout" オプションが追加されました。 |
| 1.0.11 | "safe" が設定されている場合は、"not master" エラーで接続を切断するようになりました。 |
| 1.0.9 |
"fsync" オプションが追加されました。 |
| 1.0.5 | options パラメータが追加されました。 |
例
例1 MongoCollection::save() の例
<?php
$obj = array('x' => 1);
// $obj を db に追加します
$collection->save($obj);
var_dump($obj);
// 別のフィールドを追加します
$obj['foo'] = 'bar';
// $obj をもう一度追加することはできません。_id が重複しているからです
$collection->insert($obj);
// 新しいフィールドつきの $obj で上書きします
$collection->save($obj);
?>
上の例の出力は、 たとえば以下のようになります。
array(2) {
["x"]=>
int(1)
["_id"]=>
object(MongoId)#4 (1) {
["$id"]=>
string(24) "50b6afe544415ed606000000"
}
}
忘却曲線を使ってこの知識を確実に記憶に残す
