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

  • "fsync"

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

返り値

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

エラー / 例外

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

"safe" オプションが 1 より大きい整数値に設定されているとき、 MongoCollection::$wtimeout ミリ秒以内に処理が終わらなかった場合に MongoCursorTimeoutException をスローします。

変更履歴

バージョン 説明
1.0.5 二番目のパラメータがオプションの配列に変わりました。1.0.5 より前のバージョンでは、二番目のパラメータは "safe" オプションを表す boolean 値でした。
1.0.9 "safe" オプションに整数値がわたせるようになり (以前は booleans のみでした)、さらに "fsync" オプションが追加されました。

例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($persontrue);

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

?>

参考

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


MongoCollection
PHP Manual