(PECL mongo >=0.9.0)
MongoCollection::insert — ドキュメントをコレクションに追加する
$a
[, array $options = array()
] )データベースに送信する文字列は UTF-8 でなければなりません。 UTF-8 以外の文字列を送信した場合は MongoException がスローされます。非 UTF-8 文字列を追加 (あるいは問い合わせ) するには MongoBinData を使います。
a
配列あるいはオブジェクト。オブジェクトを使う場合は、 protected や private のプロパティは保持できません。
注意:
_id のキーあるいはプロパティを持たない場合は、 新しい MongoId インスタンスを作ってそれを代入します。 ただし、パラメータを参照で渡した場合は別です。
options
追加操作についてのオプションの配列。 現在利用可能なオプションは、以下のとおりです。
"fsync"
Boolean 型で、デフォルトは FALSE です。
ジャーナリングが有効な場合、これは "j" とまったく同じ動きをします。
ジャーナリングが有効でない場合は、追加をディスク上のデータベースファイルに同期させるまで成功したと見なさないようになります。
TRUE にすると確認つき書き込みが暗黙のうちに設定され、"w" の値を 0 にします。
注意: ジャーナリングが有効な場合は、"fsync" のかわりに "j" を使いましょう。 "fsync" と "j" を同時に指定すると、エラーになります。
"j"
デフォルトは FALSE です。これを指定すると、追加をジャーナルに同期させるまで成功したと見なさないようになります。TRUE にすると確認付き書き込みと見なされ、"w" の設定を 0 に上書きします。
注意: このオプションを使っているときにジャーナリングを無効にすると、MongoDB 2.6 以降ではエラーが発生して書き込みに失敗します。古いバージョンのサーバーでは、単純にオプションの師弟を無視します。
整数で、デフォルトは MongoCursor::$timeout です。確認付き書き込みを使っている場合、これはクライアントがデータベースからのレスポンスを待ち続ける時間 (ミリ秒) を表します。この時間内にデータベースからの反応がなければ、MongoCursorTimeoutException をスローします。
"socketTimeoutMS"
"w"
WriteConcerns を参照ください。MongoClient でのデフォルト値は 1 です。
"wTimeoutMS"
WriteConcern の確認をいつまで待つか。MongoClient のデフォルトは 10000 ミリ秒です。
以下のオプションは廃止予定です。使ってはいけません。
"safe"
非推奨。WriteConcern の w オプションを使いましょう。
"timeout"
整数で、デフォルトは MongoCursor::$timeout です。確認付き書き込みを使っている場合、これはクライアントがデータベースからのレスポンスを待ち続ける時間 (ミリ秒) を表します。この時間内にデータベースからの反応がなければ、MongoCursorTimeoutException をスローします。
非推奨です。かわりに "socketTimeoutMS" オプションを使いましょう。
"wtimeout"
WriteConcern の確認をいつまで待つか。 MongoClient のデフォルトは 10000 ミリ秒です。
非推奨です。かわりに "wTimeoutMS" オプションを使いましょう。
"w" オプションが設定されている場合は、
追加の状況を含む配列を返します。
設定されていない場合は、
もし追加された配列が空でない場合に TRUE を返します
(追加された配列が空の場合は MongoException をスローします)。
配列が返された場合、その中に含まれる要素は次のようになります。
ok
これはほぼ常に 1 です (ただし last_error 自体が失敗した場合は除く)。
err
このフィールドに null 以外の値が入っている場合は、直前の操作でエラーが発生しています。 このフィールドが設定されている場合、その内容は発生したエラーを表す文字列となります。
code
データベースのエラーが発生した場合に、そのエラーコードをクライアントに戻します。
errmsg
このフィールドが設定されるのは、データベースコマンドで何か問題が発生したときです。 ok を 0 にすることと組み合わせて使います。 たとえば、もし w が設定されているときにタイムアウトが発生すると、 errmsg は "timed out waiting for slaves" そして ok は 0 になります。 このフィールドが設定されている場合、その内容は発生したエラーを表す文字列となります。
n
直近の操作が insert、update あるいは remove だった場合に、影響を受けたドキュメントの数を返します。 追加操作の場合は、この値は常に 0 です。
wtimeout
直近の操作がレプリケーション待ちでタイムアウトしたかどうか。
waited
操作がタイムアウトするまでにどれだか待ったか。
wtime
w を設定して、かつ操作が成功した場合に、 w サーバーへのレプリケートにかかった時間。
upserted
upsert が発生した場合は、このフィールドに新しいレコードの _id が格納されます。upsert の場合は、このフィールドあるいは updatedExisting のいずれかが (エラーが発生しない限り) 必ず存在します。
updatedExisting
upsert が既存の要素を更新した場合に、このフィールドが true となります。 _id が格納されます。upsert の場合は、このフィールドあるいは upsearted のいずれかが (エラーが発生しない限り) 必ず存在します。
追加したドキュメントが空だったり長さがゼロのキーが含まれていたりした場合に MongoException をスローします。 protected や private なプロパティを持つオブジェクトを追加しようとすると、 キーの長さがゼロのエラーを引き起こします。
"w" オプションが設定されていて書き込みが失敗した場合に MongoCursorException をスローします。
"w" オプションの値が 1 より大きく設定されていて、操作の完了までの時間が MongoCursor::$timeout ミリ秒をこえた場合に MongoCursorTimeoutException をスローします。サーバー上での操作は止めません。これはクライアント側でのタイムアウトです。MongoCollection::$wtimeout はミリ秒です。
| バージョン | 説明 |
|---|---|
| 1.5.0 |
"wTimeoutMS" オプションが追加されました。これは
"wtimeout" を置き換えるものです。
"wtimeout" を使うと
"socketTimeoutMS" オプションが追加されました。これは
"timeout" を置き換えるものです。
"timeout" を使うと
"safe" を使うと
|
| 1.3.4 | "wtimeout" オプションが追加されました。 |
| 1.3.0 |
"w" オプションが追加されました。
|
| 1.2.0 | "timeout" オプションが追加されました。 |
| 1.0.11 | "safe" が設定されている場合は、"not master" エラーで接続を切断するようになりました。 |
| 1.0.9 |
"safe" オプションに整数値がわたせるようになりました (以前は boolean のみでした)。 "fsync" オプションが追加されました。 "safe" オプションを使っている場合の返り値の型が配列に変わりました。 配列にはエラー情報が含まれています。"safe" オプションを使わない場合は、今までどおり boolean のままです。 |
| 1.0.5 | 二番目のパラメータがオプションの配列に変わりました。1.0.5 より前のバージョンでは、二番目のパラメータは "safe" オプションを表す boolean 値でした。 |
| 1.0.1 | "safe" オプションが設定されていて追加に失敗した場合に MongoCursorException をスローするようになりました。 |
例1 MongoCollection::insert() の _id の例
すでに存在しない場合は、_id フィールドを追加します。 パラメータの渡しかたによって、生成された _id に呼び出し元のコードからアクセスできるかどうかが変わります。
<?php
$m = new MongoClient();
$collection = $m->selectCollection('test', 'phpmanual');
// 配列リテラルを使った場合は、生成された _id にはアクセスできません
$collection->insert(array('x' => 1));
// 値渡しした配列には _id が追加されています
$a = array('x' => 2);
$collection->insert($a);
var_dump($a);
// 参照渡しした配列からは _id は見えません
$b = array('x' => 3);
$ref = &$b;
$collection->insert($ref);
var_dump($ref);
// ラップする関数がコピーオンライトを引き起こさない場合は _id にアクセスできます
function insert_no_cow($collection, $document)
{
$collection->insert($document);
}
$c = array('x' => 4);
insert_no_cow($collection, $c);
var_dump($c);
// ラップする関数がコピーオンライトを引き起こす場合は _id にアクセスできません
function insert_cow($collection, $document)
{
$document['y'] = 1;
$collection->insert($document);
}
$d = array('x' => 5);
insert_cow($collection, $d);
var_dump($d);
?>
上の例の出力は、 たとえば以下のようになります。
array(2) {
["x"]=>
int(2)
["_id"]=>
object(MongoId)#4 (0) {
}
}
array(1) {
["x"]=>
int(3)
}
array(2) {
["x"]=>
int(4)
["_id"]=>
object(MongoId)#5 (0) {
}
}
array(1) {
["x"]=>
int(5)
}
例2 MongoCollection::insert() での確認つき書き込みの例
この例は、同じ _id を持つ二つの要素を追加しようとするものです。
w が設定されていれば、
MongoCursorException がスローされます。
<?php
$person = array("name" => "Joe", "age" => 20);
$collection->insert($person);
// $person には _id フィールドができたので、
// もう一度追加しようとすると例外が発生します
try {
$collection->insert($person, array("w" => 1));
} catch(MongoCursorException $e) {
echo "Can't save the same person twice!\n";
}
?>