複数のドキュメントをコレクションに追加する

説明

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

パラメータ

a

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

注意:
追加するドキュメントが _id のキーあるいはプロパティを持たない場合は、新しい MongoId インスタンスを作ってそれを代入します。この挙動に関する詳しい情報は MongoCollection::insert() を参照ください。

options

追加操作群についてのオプションの配列。現在利用可能なオプションは、以下のとおりです。

"continueOnError"

boolean で、デフォルトは FALSE です。これを設定すると、(ID の重複などが原因で) 一括インサートが失敗したときにもデータベースは処理を続行します。その結果、一括インサート処理の挙動が一件ごとのインサートを繰り返したときと同じになります。ただし、MongoDB::lastError() をコールすると、直近の操作が失敗していなくても何か失敗があればエラーが設定されています。複数のエラーが発生したときには、 MongoDB::lastError() が返すのは最後に発生したエラーだけとなります。

注意:
continueOnError は、あくまでもデータベース側のエラーにしか影響を及ぼさないことに注意しましょう。ドキュメントそのものに問題があるもの (キーの名前が空になっているなど) をインサートしようとすると、ドライバーがこのエラーを検出してデータベースへの送信を止めてしまうので、処理はそこで終わってしまいます。ドライバー側で検出されるドキュメントのエラーに関しては、 continueOnError は何もできません。
"fsync"

Boolean 型で、デフォルトは FALSE です。ジャーナリングが有効な場合、これは "j" とまったく同じ動きをします。ジャーナリングが有効でない場合は、追加をディスク上のデータベースファイルに同期させるまで成功したと見なさないようになります。 TRUE にすると確認つき書き込みが暗黙のうちに設定され、"w" の値を 0 にします。

注意: ジャーナリングが有効な場合は、"fsync" のかわりに "j" を使いましょう。 "fsync" と "j" を同時に指定すると、エラーになります。
"j"
デフォルトは FALSE です。これを指定すると、追加をジャーナルに同期させるまで成功したと見なさないようになります。TRUE にすると確認付き書き込みと見なされ、"w" の設定を 0 に上書きします。
注意: このオプションを使っているときにジャーナリングを無効にすると、MongoDB 2.6 以降ではエラーが発生して書き込みに失敗します。古いバージョンのサーバーでは、単純にオプションの師弟を無視します。
整数で、デフォルトは MongoCursor::$timeout です。確認付き書き込みを使っている場合、これはクライアントがデータベースからのレスポンスを待ち続ける時間 (ミリ秒) を表します。この時間内にデータベースからの反応がなければ、MongoCursorTimeoutException をスローします。
"socketTimeoutMS"
"w"

WriteConcerns を参照ください。MongoClient でのデフォルト値は 1 です。
"wTimeoutMS"
WriteConcern の確認をいつまで待つか。MongoClient のデフォルトは 10000 ミリ秒です。

以下のオプションは廃止予定です。使ってはいけません。

"safe"
非推奨。WriteConcern の w オプションを使いましょう。
"timeout"
整数で、デフォルトは MongoCursor::$timeout です。確認付き書き込みを使っている場合、これはクライアントがデータベースからのレスポンスを待ち続ける時間 (ミリ秒) を表します。この時間内にデータベースからの反応がなければ、MongoCursorTimeoutException をスローします。
警告
非推奨です。かわりに "socketTimeoutMS" オプションを使いましょう。
"wtimeout"

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

警告
非推奨です。かわりに "wTimeoutMS" オプションを使いましょう。

返り値

w を設定して書き込みの確認をするようにしている場合は、追加の状況 ("ok") と発生したエラー ("err") を連想配列で返します。設定されていないときは、一括追加の送信に成功すれば TRUE、失敗すれば FALSE を返します。

エラー / 例外

追加したドキュメントが空だったり長さがゼロのキーが含まれていたりした場合に MongoException をスローします。 protected や private なプロパティを持つオブジェクトを追加しようとすると、キーの長さがゼロのエラーを引き起こします。

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

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

変更履歴

バージョン	説明
1.5.0	"wTimeoutMS" オプションが追加されました。これは "wtimeout" を置き換えるものです。 "wtimeout" を使うと `E_DEPRECATED` が発生します。 "socketTimeoutMS" オプションが追加されました。これは "timeout" を置き換えるものです。 "timeout" を使うと `E_DEPRECATED` が発生します。 "safe" を使うと `E_DEPRECATED` が発生します。
1.3.4	"wtimeout" オプションが追加されました。
1.3.0	"w" オプションが追加されました。
1.2.7	"continueOnError" オプションが追加されました。
1.0.9	"safe" オプションに整数値がわたせるようになりました (以前は boolean のみでした)。 "fsync" オプションが追加されました。
1.0.5	`options` パラメータが追加されました。

例

例1 MongoCollection::batchInsert() の例

バッチ挿入を使用すると、多くの要素を一度にデータベースに追加できます。


<?php

$users = array();
for ($i = 0; $i<100; $i++) {
  $users[] = array('username' => 'user'.$i, 'i' => $i);
}

$mongo = new MongoClient();
$collection = $mongo->my_db->users;
$collection->drop();

$collection->batchInsert($users);

foreach ($users as $user) {
  echo $user['_id']."\n"; // MongoId のインスタンスが格納されています
}

$users = $collection->find()->sort(array('i' => 1));
foreach ($users as $user) {
    var_dump($user['username']);
}

?>

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

4bf43ac68ead0e1971000000
4bf43ac68ead0e1971010000
4bf43ac68ead0e1971020000
...
string(5) "user1"
string(5) "user2"
string(5) "user3"
...

例2 MongoCollection::batchInsert() でエラーを無視する例


<?php

$con = new Mongo;
$db = $con->demo;

$doc1 = array(
        '_id' => new MongoId('4cb4ab6d7addf98506010001'),
        'id' => 1,
        'desc' => "ONE",
);
$doc2 = array(
        '_id' => new MongoId('4cb4ab6d7addf98506010002'),
        'id' => 2,
        'desc' => "TWO",
);
$doc3 = array(
        '_id' => new MongoId('4cb4ab6d7addf98506010002'), // same _id as above
        'id' => 3,
        'desc' => "THREE",
);
$doc4 = array(
        '_id' => new MongoId('4cb4ab6d7addf98506010004'),
        'id' => 4,
        'desc' => "FOUR",
);

$c = $db->selectCollection('c');
$c->batchInsert(
    array($doc1, $doc2, $doc3, $doc4),
    array('continueOnError' => true)
);

$docs = $c->find();
foreach ($docs as $doc) {
    var_dump($doc['desc']);
}
?>

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

string(3) "ONE"
string(3) "TWO"
string(4) "FOUR"

参考

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