MongoCollection
PHP Manual

MongoCollection::insert

(PECL mongo >=0.9.0)

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

説明

public bool|array 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 値を返します (空の配列は追加されません)。

配列が返された場合、その中に含まれる要素は次のようになります。

ok

これは常に 1 です (ただし last_error 自体が失敗した場合は除く)。

err

このフィールドに null 以外の値が入っている場合は、直前の操作でエラーが発生しています。 このフィールドが設定されている場合、その内容は発生したエラーを表す文字列となります。

code

データベースのエラーが発生した場合に、そのエラーコードをクライアントに戻します。

errmsg

このフィールドが設定されるのは、データベースコマンドで何か問題が発生したときです。 ok を 0 にすることと組み合わせて使います。 たとえば、もし w が設定されているときにタイムアウトが発生すると、 errmsg は "timed out waiting for slaves" そして ok は 0 になります。 このフィールドが設定されている場合、その内容は発生したエラーを表す文字列となります。

n

直近の操作が insert、update あるいは remove だった場合に、影響を受けた行の数を返します。 of objects affected will be returned.

wtimeout

直近の操作がレプリケーション待ちでタイムアウトしたかどうか。

waited

操作がタイムアウトするまでにどれだか待ったか。

wtime

w を設定して、かつ操作が成功した場合に、 w サーバーへのレプリケートにかかった時間。

upserted

upsert が発生した場合は、このフィールドに新しいレコードの _id が格納されます。upsert の場合は、このフィールドあるいは updatedExisting のいずれかが (エラーが発生しない限り) 必ず存在します。

updatedExisting

upsert が既存の要素を更新した場合に、このフィールドが true となります。 _id が格納されます。upsert の場合は、このフィールドあるいは upsearted のいずれかが (エラーが発生しない限り) 必ず存在します。

エラー / 例外

"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.9 "safe" オプションを使っている場合の返り値の型が配列に変わりました。 配列にはエラー情報が含まれています。"safe" オプションを使わない場合は、今までどおり boolean のままです。
1.0.11 "safe" が設定されている場合は、"not master" エラーで接続を切断するようになりました。
1.2.0 timeout オプションが追加されました。
1.3.0 options パラメータで、boolean だけを渡して安全な追加を指定することができなくなりました。 同じことをするには array('safe' => true) としなければなりません。

例

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

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

<?php

$m = new Mongo(); 
$db = $m->selectDB('test');
$collection = new MongoCollection($db, 'phpmanual');

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

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

?>

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

array(2) {
  ["x"]=>
  int(12)
  ["_id"]=>
  object(MongoId)#4 (0) {
  }
}
array(12) {
  ["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";
}

?>

参考

MongoCollection
PHP Manual