MongoCollection
PHP Manual

MongoCollection::insert

(PECL mongo >=0.9.0)

MongoCollection::insert — 配列をコレクションに追加する

説明

public mixed MongoCollection::insert ( array $a [, array $options = array() ] )

データベースに送信する文字列は UTF-8 でなければなりません。 UTF-8 以外の文字列を送信した場合は MongoException がスローされます。非 UTF-8 文字列を追加 (あるいは問い合わせ) するには MongoBinData を使います。

パラメータ

a

配列。

options

追加時のオプション。

  • "safe"

    boolean あるいは整数値で、デフォルトは FALSE です。FALSE の場合、データベースからの応答を待たずにプログラムを続行します。 TRUE の場合、プログラムはデータベースからの応答を待ち、 追加に失敗したときには MongoCursorException をスローします。

    レプリケーションを使っていてマスタを変更している場合、もし "safe" を使っていればドライバはマスタとの接続を切断して例外をスローし、 次の操作時に新しいマスタを探そうとします (新しいマスタに対して操作を再試行するかどうかは アプリケーション側で判断しなければなりません)。

    レプリカセットで "safe" を 使わずに マスタを変更する場合は、ドライバがその変更について知るすべがありません。 そのため、何もエラーを出さずに書き込みに失敗し続けます。

    safe が整数値の場合は、 指定した数のマシンで追加が成功するまでは成功したと見なしません (処理がタイムアウトした場合は例外をスローします。wtimeout を参照ください)。 これは、コレクションに設定された w 変数をオーバーライドします。

  • "fsync"

    boolean で、デフォルトは FALSE です。 追加操作がディスク上に同期されるまで成功とは見なさないようにさせます。 TRUE の場合は "安全な" 追加操作が前提となり、 safe の設定を FALSE にオーバーライドします。

  • "timeout"

    整数値。デフォルトは MongoCursor::$timeout です。 "safe" が設定されている場合に、クライアントがデータベースからの応答をどれだけ待つかを (ミリ秒単位で) 指定します。ここで指定した時間内にデータベースからの応答がない場合は MongoCursorTimeoutException がスローされます。

返り値

safe が設定されている場合は、 追加結果を含む配列を返します。設定されていない場合は、 配列が空でなかったかどうかをあらわす boolean 値を返します (空の配列は追加されません)。

エラー / 例外

"safe" オプションが設定されていて追加に失敗した場合に MongoCursorException をスローします (バージョン 1.0.1 以降)。

"safe" オプションが設定されているときに MongoCollection::$wtimeout ミリ秒以内に処理が終わらなければ MongoCursorTimeoutException をスローします。 これはサーバ上の操作を終了させるわけではなく、あくまでもクライアント側のタイムアウトです。

変更履歴

バージョン 説明
1.0.5 二番目のパラメータがオプションの配列に変わりました。1.0.5 より前のバージョンでは、二番目のパラメータは "safe" オプションを表す boolean 値でした。
1.0.9 "safe" オプションに整数値がわたせるようになり (以前は booleans のみでした)、さらに "fsync" オプションが追加されました。
1.0.11 "safe" が設定されている場合は、"not master" エラーで接続を切断するようになりました。
1.2.0 timeout オプションが追加されました。

例

例1 MongoCollection::insert() の _id の例

オブジェクトを挿入すると、参照渡しでない限りはそこに _id フィールドを追加します。

<?php

$a = array('x' => 1);
$collection->insert($a);
var_dump($a);

$b = array('x' => 1);
$ref = &$b;
$collection->insert($ref);
var_dump($ref);

?>

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

array(2) {
  ["x"]=>
  int(1)
  ["_id"]=>
  object(MongoId)#4 (0) {
  }
}
array(1) {
  ["x"]=>
  int(1)
}

例2 MongoCollection::insert() での safe の例

この例は、同じ _id を持つ二つの要素を追加しようとするものです。 safe が設定されていれば、 MongoCursorException がスローされます。

<?php

$person = array("name" => "Joe", "age" => 20);
$collection->insert($person, true);

// $person には _id フィールドができたので、
// もう一度追加しようとすると例外が発生します
try {
    $collection->insert($person, true);
}
catch(MongoCursorException $e) {
    echo "Can't save the same person twice!\n";
}

?>

参考

MongoDB コアドキュメントの » insert を参照ください。

MongoCollection
PHP Manual