MongoCollection::batchInsert

(PECL mongo >=0.9.0)

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

説明

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

パラメータ

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 以降ではエラーが発生して書き込みに失敗します。古いバージョンのサーバーでは、単純にオプションの指定を無視します。

  • "socketTimeoutMS"

    このオプションは、ソケット通信の制限時間を、ミリ秒単位で指定します。この時間内にサーバーからの反応がなければ、MongoCursorTimeoutException をスローします。この場合、サーバー側で書き込み処理が行われたのかどうかを判断できなくなります。-1 を指定すると、永遠にブロックします。MongoClient のデフォルト値は 30000 (30 秒) です。

  • "w"

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

  • "wTimeoutMS"

    このオプションは、書き込み確認を待つ制限時間をミリ秒単位で指定します。これが書き込み操作に適用されるのは、"w" が 1 より大きい場合のみです。というのも、タイムアウトはレプリケーションに関する機能だからです。この時間内に書き込み確認ができなかった場合は MongoCursorException をスローします。0 を指定すると、永遠にブロックし続けます。MongoClient でのデフォルトは 10000 ミリ秒 (10 秒) です。

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

  • "safe"

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

  • "timeout"

    非推奨。"socketTimeoutMS" のエイリアス。

  • "wtimeout"

    廃止予定。"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"

参考