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

追加時のオプション。

  • "w"

    WriteConcerns を参照ください。MongoClient でのデフォルト値は 1 です。

  • "fsync"

    デフォルトは FALSE です。 これを指定すると、追加をディスクに同期させるまで成功したと見なさないようになります。 TRUE にすると、w の設定を 0 に上書きします。

  • "timeout"

    整数で、デフォルトは MongoCursor::$timeout です。 "safe" が設定されている場合、これはクライアントがデータベースからのレスポンスを待ち続ける時間 (ミリ秒) を表します。 この時間内にデータベースからの反応がなければ、MongoCursorTimeoutException をスローします。

  • "safe"

    非推奨。WriteConcern の w オプションを使いましょう。

返り値

"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 だった場合に、影響を受けた行の数を返します。 of objects affected will be returned.

wtimeout

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

waited

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

wtime

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

upserted

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

updatedExisting

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

エラー / 例外

追加された配列が空の場合に MongoException をスローします。

"w" オプションが設定されていて書き込みが失敗した場合に MongoCursorException をスローします。

"w" オプションの値が 1 より大きく設定されていて、操作の完了までの時間が MongoCursor::$timeout ミリ秒をこえた場合に MongoCursorTimeoutException をスローします。サーバー上での操作は止めません。これはクライアント側でのタイムアウトです。MongoCollection::$wtimeout はミリ秒です。

変更履歴

バージョン 説明
1.3.0 options パラメータで、boolean だけを渡して確認付きの書き込みを指定することができなくなりました。 同じことをするには array('w' => 1) (MongoClient のデフォルト) としなければなりません。
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 フィールドを追加します。

<?php

$m = new MongoClient();
$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() での確認つき書き込みの例

この例は、同じ _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";
}

?>

参考

MongoCollection
PHP Manual