/ /

一括書き込み操作

Overview

このガイドでは、一括書込み操作を使用して、1 つのデータベース呼び出しで複数の書込み操作を実行する方法を学習できます。

ドキュメントを挿入し、複数の他のドキュメントを更新してから、ドキュメントを削除するシナリオを考えてみましょう。個々のメソッドを使用する場合、各操作には独自のデータベース呼び出しが必要です。

一括書き込み操作を使用すると、より少ないデータベース呼び出しで複数の書き込み操作を実行できます。次のレベルで一括書き込み操作を実行できます。

クライアント :アプリケーションがMongoDB Serverバージョン 8.0 以降に接続している場合は、MongoDB\Client::bulkWrite() メソッドを使用して、同じクラスター内の複数のコレクションとデータベースに対して一括書込み操作を実行できます。このメソッドは、1 回のデータベース呼び出しですべての書き込み操作を実行します。この機能の詳細については、Mongo.bulkWrite()参照（ MongoDB Serverマニュアル）
コレクション : MongoDB\Collection::bulkWrite() メソッドを使用して、単一のコレクションに対して一括書き込み操作を実行できます。このメソッドは、書込み (write)操作の各タイプに対してデータベースを呼び出します。例、メソッドは 1 回の呼び出しで複数のアップデート操作を実行できますが、挿入操作と置換操作のためにデータベースに対して 2 回個別の呼び出しを行います。

サンプルデータ

このガイドの例では、Atlasサンプルデータセットの sample_restaurants.restaurants コレクションと sample_mflix.movies コレクションを使用します。MongoDB Atlasクラスターを無料で作成して、サンプルデータセットをロードする方法については、Atlas を使い始めるを参照してください。

クライアント一括書込み (write)

PHPライブラリ v2.1 を使用しており、 MongoDB Server 8.0 以降を実行中配置に接続する場合、MongoDB\Client::bulkWrite() メソッドを使用して同じクラスター内の複数のデータベースとコレクションに書込むことができます。このメソッドは、1 回の呼び出しですべての書き込み操作を実行します。

まず、MongoDB\ClientBulkWrite ビルダを使用して、実行する書込み操作を指定するBulkWriteCommandインスタンスを作成します。次のコードは、createWithCollection() メソッドを使用して、MongoDB\Collectionインスタンスから ClientBulkWriteインスタンスを作成する方法を示しています。

$restaurantCollection = $client->sample_restaurants->restaurants;
$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);

次に、ClientBulkWriteインスタンスで次の書き込みメソッドの 1 つ以上を呼び出して、一括書き込み操作を構築します。

deleteOne()
deleteMany()
insertOne()
replaceOne()
updateOne()
updateMany()

後続の書き込み操作で別の名前空間を選択するには、次のコードに示すように、ClientBulkWriteインスタンスで withCollection() メソッドを呼び出します。

$movieCollection = $client->sample_mflix->movies;
$bulkWrite = $bulkWrite->withCollection($movieCollection);

次のセクションでは、ClientBulkWriteクラスの作成と使用を使用して、一括書き込みで書込み操作を指定する方法を示します。「一括操作の実行」セクションでは、ClientBulkWriteオブジェクトを bulkWrite() メソッドに渡して一括操作を実行する方法が説明されています。

挿入操作

挿入操作を指定するには、ClientBulkWriteインスタンスで insertOne() メソッドを呼び出します。

次の例では、sample_restaurants.restaurants コレクションと sample_mflix.movies コレクションへのドキュメントの挿入を指定しています。

$restaurantCollection = $client->sample_restaurants->restaurants;
$movieCollection = $client->sample_mflix->movies;
$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
$bulkWrite->insertOne(['name' => 'Mongo Deli', 'cuisine' => 'Sandwiches']);
$bulkWrite = $bulkWrite->withCollection($movieCollection);
$bulkWrite->insertOne(['title' => 'The Green Ray', 'year' => 1986]);

アップデート操作

最初に一致するドキュメントのアップデート操作を指定するには、ClientBulkWriteインスタンスで updateOne() メソッドを呼び出します。

次の例では、sample_restaurants.restaurantsコレクション内の name 値が 'Dandelion Bakery' である最初のドキュメントに対する $set アップデートを指定します。

$restaurantCollection = $client->sample_restaurants->restaurants;
$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
$bulkWrite->updateOne(
    ['name' => 'Dandelion Bakery'],
    ['$set' => ['grade' => 'B+']],
    ['upsert' => true],
);

複数のドキュメントを更新するには、updateMany() メソッドを呼び出します。指定された操作は、 クエリフィルターに一致するすべてのドキュメントを更新します。

次の例では、name の値が 'Starbucks' である、sample_restaurants.restaurantsコレクション内の一致するすべてのドキュメントに対する $set アップデートを指定します。

$restaurantCollection = $client->sample_restaurants->restaurants;
$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
$bulkWrite->updateMany(
    ['name' => 'Starbucks'],
    ['$set' => ['cuisine' => 'Coffee (Chain)']],
);

置換操作

最初に一致するドキュメントで置換操作を指定するには、ClientBulkWriteインスタンスで replaceOne() メソッドを呼び出します。

次の例では、name の値が 'Dandelion Bakery' である sample_restaurants.restaurantsコレクション内の最初のドキュメントに対する置換操作を指定します。

$restaurantCollection = $client->sample_restaurants->restaurants;
$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
$bulkWrite->replaceOne(
    ['name' => 'Dandelion Bakery'],
    ['name' => 'Flower Patisserie', 'cuisine' => 'Bakery & Cafe'],
);

削除操作

最初に一致するドキュメントの削除操作を指定するには、ClientBulkWriteインスタンスで deleteOne() メソッドを呼び出します。

次の例では、sample_restaurants.restaurantsコレクション内の borough 値が 'Queens' である最初のドキュメントの削除を指定します。

$restaurantCollection = $client->sample_restaurants->restaurants;
$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
$bulkWrite->deleteOne(
    ['borough' => 'Queens'],
);

複数のドキュメントを削除するには、deleteMany() メソッドを呼び出します。指定された操作は、クエリフィルターに一致するすべてのドキュメントを削除します。

次の例では、連続する 2 文字の 'p' 文字を含む name 値を持つ sample_restaurants.restaurantsコレクション内のすべてのドキュメントの削除を指定します。

$restaurantCollection = $client->sample_restaurants->restaurants;
$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
$bulkWrite->deleteMany(
    ['name' => ['$regex' => 'p{2,}']],
);

一括操作の実行

書込み操作を指定するために ClientBulkWriteインスタンスを作成したら、それを MongoDB\Client::bulkWrite() メソッドに渡します。デフォルトでは、これらのメソッドは ClientBulkWrite の構築時に定義した順序で操作を実行します。

次のコードは、bulkWrite() メソッドを使用して複数の名前空間で一括書き込み操作を実行する方法を示しています。

$restaurantCollection = $client->sample_restaurants->restaurants;
$movieCollection = $client->sample_mflix->movies;
// Creates the bulk write command and sets the target namespace.
$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
// Specifies insertion of one document.
$bulkWrite->insertOne(['name' => 'Mongo Deli', 'cuisine' => 'Sandwiches']);
// Specifies a `$set` update to one document with the upsert option
// enabled.
$bulkWrite->updateOne(
    ['name' => 'Dandelion Bakery'],
    ['$set' => ['grade' => 'B+']],
    ['upsert' => true],
);
// Changes the target namespace.
$bulkWrite = $bulkWrite->withCollection($movieCollection);
// Specifies insertion of one document.
$bulkWrite->insertOne(['title' => 'The Green Ray', 'year' => 1986]);
// Specifies deletion of documents in which `title` has two consective
// 'd' characters.
$bulkWrite->deleteMany(
    ['title' => ['$regex' => 'd{2,}']],
);
// Specifies replacement of one document.
$bulkWrite->replaceOne(
    ['runtime' => ['$gte' => 200]],
    ['title' => 'Seven Samurai', 'runtime' => 203],
);
// Performs the bulk write operation.
$result = $client->bulkWrite($bulkWrite);
// Prints a summary of results.
echo 'Inserted documents: ', $result->getInsertedCount(), PHP_EOL;
echo 'Modified documents: ', $result->getModifiedCount(), PHP_EOL;
echo 'Deleted documents: ', $result->getDeletedCount(), PHP_EOL;

Inserted documents: 2
Modified documents: 2
Deleted documents: 200

一括書き込みをカスタマイズする

クライアント一括書き込み操作の動作を変更するには、パラメーターとしてオプション値を指定する配列を ClientBulkWrite コンストラクターに渡します。次の表では、配列に設定できるオプションについて説明しています。

オプション	説明
`bypassDocumentValidation`	操作がドキュメントの検証をバイパスするかどうかを指定します。これにより、スキーマ検証要件を満たしていないドキュメントを修正できます（存在する場合）。スキーマ検証の詳細については、MongoDB Server マニュアルの「スキーマ検証」を参照してください。デフォルトは `false` に設定されています。
`comment`	操作にコメントを付けます。詳細については、 MongoDB Serverマニュアルの「挿入コマンドフィールドのガイド」を参照してください。
`let`	操作の読みやすさを向上させるために、の値のリストを含むドキュメントを指定します。値は、ドキュメントフィールドを参照しない定数または閉じた式である必要があります。詳細については、 MongoDB Serverマニュアルの let ステートメントを参照してください。
`ordered`	`true` に設定されている場合: 1 つの書き込み (write) が失敗すると、操作は残りの書き込み (write) を実行せずに停止し、例外がスローされます。 `false` に設定されている場合: 1 つの書き込み (write) が失敗すると、操作は残りの書き込み (write) 操作がある場合は続行し、その後例外がスローされます。デフォルトは `true` です。
`verboseResults`	詳細な結果を返すかどうかを指定します。デフォルトは `false` です。

次の例では、ClientBulkWriteインスタンスを作成し、ordered オプションを false に設定します。

$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection(
    $restaurantCollection,
    ['ordered' => false],
);

注意

順序なし動作

順序なしの一括操作では、実行順序は保証されません。この順序は、ランタイムを最適化するために一覧表示する方法とは異なる場合があります。順序なしの一括書き込みで次の書き込み操作を指定するとします。

$bulkWrite->insertOne(['_id' => 4045, 'title' => 'The Green Ray']);
$bulkWrite->deleteOne(['_id' => 4045]);

ライブラリは最初にいずれかの操作を実行する可能性があるため、結果には削除されたドキュメントが 1 つ表示される場合もあります。

また、 bulkWrite() メソッドを呼び出すときにオプションを渡して、操作に使用するクライアントセッションまたは書込み保証 (write concern)を指定することもできます。

戻り値

MongoDB\Client::bulkWrite() メソッドは MongoDB\BulkWriteCommandResultオブジェクトを返します。このクラスには、次のメソッドが含まれています。

方式	説明
`getInsertedCount()`	一括書き込み (write) コマンドのすべての挿入操作によって挿入されたドキュメントの合計数を返します。
`getMatchedCount()`	一括書き込み (write)コマンドにおけるすべての更新および置換操作によって一致したドキュメントの合計数を返します。
`getModifiedCount()`	一括書き込み (write) におけるすべての更新操作と置換操作によって変更されたドキュメントの合計数を返します。
`getUpsertedCount()`	一括書き込み (write) コマンドのすべての更新操作と置換操作によってアップサートされたドキュメントの合計数を返します。
`getDeletedCount()`	一括書き込みコマンド内のすべての削除操作によって削除するドキュメントの合計数を返します。
`getInsertResults()`	成功した各挿入操作の結果のマップを返します。各操作は整数キーで表されます。このキーには、挿入された `_id` 値など、操作に対応する情報を含むドキュメントが含まれています。
`getUpdateResults()`	成功した各更新操作の結果のマップを返します。各操作は整数キーで表されます。このキーには、操作に対応する情報を含むドキュメントが含まれます。
`getDeleteResults()`	成功した各削除操作の結果のマップを返します。各操作は整数キーで表されます。このキーには、操作に対応する情報を含むドキュメントが含まれます。
`isAcknowledged()`	サーバーがブルク操作を認識したかどうかを示すブール値を返します。

コレクションの一括書込み (write)

一括書込み操作を実行するには、書込み操作の配列を MongoDB\Collection::bulkWrite() メソッドに渡します。書込み操作を指定するには、次の構文を使用します。

[
    [ 'deleteMany' => [ $filter ] ],
    [ 'deleteOne'  => [ $filter ] ],
    [ 'insertOne'  => [ $document ] ],
    [ 'replaceOne' => [ $filter, $replacement, $options ] ],
    [ 'updateMany' => [ $filter, $update, $options ] ],
    [ 'updateOne'  => [ $filter, $update, $options ] ],
]

Tip

削除する、挿入、置換、および更新操作の詳細については、 CRUD操作を参照してください。

bulkWrite() メソッドを呼び出すと、ライブラリは配列で指定した順序で書込み操作を自動的に実行します。書き込み操作を任意の順序で実行するよう bulkWrite() に指示する**学ぶ方法については**、一括書き込み操作のカスタマイズを参照してください。

例

この例では、 restaurantsコレクションに対して次の書き込み操作を実行します。

挿入操作は、 name値が'Mongo's Deli'であるドキュメントを挿入します
name値が'Mongo's Deli'であるドキュメントのcuisineフィールドを更新する更新操作
borough値が'Manhattan'であるすべてのドキュメントを削除する削除操作

$restaurantCollection = $client->sample_restaurants->restaurants;
$result = $restaurantCollection->bulkWrite(
    [
        [
            'insertOne' => [
                ['name' => 'Mongo\'s Deli'],
                ['cuisine' => 'Sandwiches'],
                ['borough' => 'Manhattan'],
                ['restaurant_id' => '1234'],
            ],
        ],
        [
            'updateOne' => [
                ['name' => 'Mongo\'s Deli'],
                ['$set' => ['cuisine' => 'Sandwiches and Salads']],
            ],
        ],
        [
            'deleteMany' => [
                ['borough' => 'Manhattan'],
            ],
        ],
    ],
);

注意

ライブラリが一括操作を実行する場合、ターゲットコレクションの書込み保証 (write concern)が使用されます。ドライバーは、実行順序に関係なく、すべての操作を試行した後にすべての書込み保証 (write concern)エラーを報告します。