MongoCollection::group
MongoCollection::remove
MongoCollection
PHP Manual

# MongoCollection::insert

(PECL mongo >=0.9.0)

MongoCollection::insert — ドキュメントをコレクションに追加する

### 説明

public bool|array MongoCollection::insert ( array|object `$a` [, array `$options` = array() ] )

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

### パラメータ

`a`

  配列あるいはオブジェクト。オブジェクトを使う場合は、 protected や private のプロパティは保持できません。

  > 注意:

  > _id のキーあるいはプロパティを持たない場合は、 新しい MongoId インスタンスを作ってそれを代入します。 ただし、パラメータを参照で渡した場合は別です。

`options`

  追加時のオプション。

  - "fsync"

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

  - "j"

    デフォルトは `FALSE` です。 これを指定すると、追加をジャーナルに同期させるまで成功したと見なさないようになります。 `TRUE` にすると確認付き書き込みと見なされ、w の設定を 0 に上書きします。

  - "w"

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

  - "wtimeout"

    WriteConcern の確認をいつまで待つか。 MongoClient のデフォルトは 10000 ミリ秒です。

  - "safe"

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

  - "timeout"

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

### 返り値

"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.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 フィールドを追加します。 パラメータの渡しかたによって、生成された _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";
}
?>`

### 参考

- MongoCollection::batchInsert() - 複数のドキュメントをコレクションに追加する
- MongoCollection::update() - 指定した条件にもとづいてレコードを更新する
- MongoCollection::find() - コレクションに問い合わせ、結果セットの MongoCursor を返す
- MongoCollection::remove() - レコードをコレクションから削除する
- MongoDB コアドキュメントの » insert

MongoCollection::group
MongoCollection::remove
MongoCollection
PHP Manual