一括書き込み操作

Overview

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

コレクションにドキュメントを挿入し、複数の他のドキュメントを更新してから、ドキュメントを削除するシナリオを考えてみましょう。個々の関数を使用する場合、各操作には独自のデータベース呼び出しが必要です。代わりに、一括操作を使用して、データベースへの呼び出し回数を減らすことができます。

サンプルデータ

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

一括書き込み操作の開始

一括書き込み操作を実行中前に、mongoc_collection_create_bulk_operation_with_opts() 関数を呼び出します。この関数は、実行する一括書き込みに関する指示を保存するために使用できる mongoc_bulk_operation_t の値を返します。

mongoc_collection_create_bulk_operation_with_opts() 関数は次のパラメータを受け入れます。

コレクション : 変更するコレクションを指定します
オプションドキュメント:操作をカスタマイズするためのオプションを指定します。またはNULL

次の例では、 mongoc_collection_create_bulk_operation_with_opts() 関数を呼び出し、restaurantsコレクションをパラメーターとして渡します。

mongoc_bulk_operation_t *bulk =
   mongoc_collection_create_bulk_operation_with_opts(collection, NULL);

その後、一括操作に書込み (write) 指示を追加できます。詳細については、次の「書込み操作の定義」セクションを参照してください。

書込み (write) 操作を定義する

書込み操作を定義し、次のメソッドを呼び出して一括書込みに追加するには、

mongoc_bulk_operation_insert_with_opts()
mongoc_bulk_operation_update_one_with_opts()
mongoc_bulk_operation_update_many_with_opts()
mongoc_bulk_operation_replace_one_with_opts()
mongoc_bulk_operation_remove_one_with_opts()
mongoc_bulk_operation_remove_many_with_opts()

次のセクションでは、これらのメソッドを使用して対応する書込み操作を指定する方法を示します。

挿入操作

挿入操作を実行するには、mongoc_bulk_operation_t に挿入指示を追加します。これにより、一括書込みの一部として操作がキューに入れられます。

次の例では、挿入するドキュメントと mongoc_bulk_operation_t の値をパラメーターとして渡して、mongoc_bulk_operation_insert_with_opts() 関数を呼び出します。

bson_t *insert_doc = BCON_NEW(
    "name", BCON_UTF8("Mongo's Deli"),
    "cuisine", BCON_UTF8("Sandwiches"),
    "borough", BCON_UTF8("Manhattan"),
    "restaurant_id", BCON_UTF8("1234")
);
bson_error_t error;
if (!mongoc_bulk_operation_insert_with_opts(bulk, insert_doc, NULL, &error)) {
    fprintf(stderr, "Failed to add insert operation: %s\n", error.message);
}
bson_destroy(insert_doc);

複数のドキュメントを挿入するには、ドキュメントごとに mongoc_bulk_operation_insert_with_opts() を呼び出します。

アップデート操作

更新操作を実行するには、mongoc_bulk_operation_t に更新指示を追加します。これにより、一括書込みの一部として操作がキューに入れられます。

次の例では、クエリフィルター、ドキュメントの更新、mongoc_bulk_operation_t 値をパラメーターとして渡して、mongoc_bulk_operation_update_one_with_opts() 関数を呼び出します。

bson_t *filter_doc = BCON_NEW("name", BCON_UTF8("Mongo's Deli"));
bson_t *update_doc = BCON_NEW("$set", "{", "cuisine", BCON_UTF8("Sandwiches and Salads"), "}");
bson_error_t error;
if (!mongoc_bulk_operation_update_one_with_opts(bulk, filter_doc, update_doc, NULL, &error)) {
    fprintf(stderr, "Failed to add update operation: %s\n", error.message);
}
bson_destroy(filter_doc);
bson_destroy(update_doc);

複数のドキュメントを更新するには、mongoc_bulk_operation_update_many_with_opts() を呼び出して同じパラメータを渡します。これは、クエリフィルターに一致するすべてのドキュメントを更新するようにドライバーに指示します。

次の例では、アップデートの多くの操作を一括書込み (write) に対してキューに入れています。

bson_t *filter_doc = BCON_NEW("name", BCON_UTF8("Mongo's Deli"));
bson_t *update_doc = BCON_NEW("$set", "{", "cuisine", BCON_UTF8("Sandwiches and Salads"), "}");
bson_error_t error;
if (!mongoc_bulk_operation_update_many_with_opts(bulk, filter_doc, update_doc, NULL, &error)) {
    fprintf(stderr, "Failed to add update operation: %s\n", error.message);
}
bson_destroy(filter_doc);
bson_destroy(update_doc);

置換操作

置換操作、指定されたドキュメントのすべてのフィールドと値が削除され、新しいフィールドと値に置き換えられます。置換操作を実行するには、置換手順を mongoc_bulk_operation_t に追加します。これにより、一括書込みの一部として操作がキューに入れられます。

次の例では、クエリフィルター、置換ドキュメント、 mongoc_bulk_operation_t 値をパラメーターとして渡して、mongoc_bulk_operation_replace_one_with_opts() 関数を呼び出します。

bson_t *filter_doc = BCON_NEW("restaurant_id", BCON_UTF8("1234"));
bson_t *replace_doc = BCON_NEW(
    "name", BCON_UTF8("Mongo's Deli"),
    "cuisine", BCON_UTF8("Sandwiches and Salads"),
    "borough", BCON_UTF8("Brooklyn"),
    "restaurant_id", BCON_UTF8("5678")
);
bson_error_t error;
if (!mongoc_bulk_operation_replace_one_with_opts(bulk, filter_doc, replace_doc, NULL, &error)) {
    fprintf(stderr, "Failed to add replace operation: %s\n", error.message);
}
bson_destroy(filter_doc);
bson_destroy(replace_doc);

複数のドキュメントを置き換えるには、ドキュメントごとに mongoc_bulk_operation_replace_one_with_opts() を呼び出します。

削除操作

削除操作を実行するには、mongoc_bulk_operation_t に削除手順を追加します。これにより、一括書込みの一部として操作がキューに入れられます。

次の例では、クエリフィルターと mongoc_bulk_operation_t の値をパラメーターとして渡して、mongoc_bulk_operation_remove_one_with_opts() 関数を呼び出します。

bson_t *filter_doc = BCON_NEW("restaurant_id", BCON_UTF8("5678"));
bson_error_t error;
if (!mongoc_bulk_operation_remove_one_with_opts(bulk, filter_doc, NULL, &error)) {
    fprintf(stderr, "Failed to add delete operation: %s\n", error.message);
}
bson_destroy(filter_doc);

複数のドキュメントを削除するには、mongoc_bulk_operation_remove_many_with_opts() 関数を呼び出して同じパラメータを渡します。これは、クエリフィルターに一致するすべてのドキュメントを削除するようにドライバーに指示します。

次の例では、多数の削除操作を一括書き込みでキューに入れています。

bson_t *filter_doc = BCON_NEW("borough", BCON_UTF8("Manhattan"));
bson_error_t error;
if (!mongoc_bulk_operation_remove_many_with_opts(bulk, filter_doc, NULL, &error)) {
    fprintf(stderr, "Failed to add delete operation: %s\n", error.message);
}
bson_destroy(filter_doc);

一括操作の実行

一括書き込みでキューに入れられた各書き込み操作を実行するには、mongoc_bulk_operation_execute() 関数を呼び出します。この関数は次のパラメーターを受け入れます:

mongoc_bulk_operation_t 値 : 各書き込み操作の指示が含まれています
結果のロケーション :操作結果を含む上書き可能なストレージへのポインターを指定します。またはNULL
エラーロケーション : エラー値のロケーションを指定します。またはNULL

ドキュメントを一括書き込み (write) するには、次の構文を使用します。

bson_error_t error;
mongoc_bulk_operation_t *bulk =
   mongoc_collection_create_bulk_operation_with_opts(collection, NULL);
bson_t *insert_doc = BCON_NEW(
    "<field name>", BCON_UTF8("<value>"),
    "<field name>", BCON_UTF8("<value>"),
    "<field name>", BCON_UTF8("<value>"),
    "<field name>", BCON_UTF8("<value>")
);
mongoc_bulk_operation_insert(bulk, insert_doc);
bson_destroy(insert_doc);
    
bson_t *query = BCON_NEW("<field to match>", BCON_UTF8("<value to match>"));
bson_t *update = BCON_NEW("$set", "{", "<field name>", BCON_UTF8("<value>"), "}");
mongoc_bulk_operation_update_one(bulk, query, update, false);
bson_destroy(query);
bson_destroy(update);
bool result = mongoc_bulk_operation_execute(bulk, NULL, &error);
if (!result) {
    fprintf(stderr, "Bulk operation error: %s\n", error.message);
}
mongoc_bulk_operation_destroy(bulk);

次の例では、関数を呼び出して、このガイドの前のセクションで指定されている挿入、アップデート、置換、および削除操作を実行します。mongoc_bulk_operation_execute()

bson_error_t error;
bool result = mongoc_bulk_operation_execute(bulk, NULL, &error);
if (!result) {
    printf("Bulk operation error: %s\n", error.message);
}
mongoc_bulk_operation_destroy(bulk);

いずれかの書込み操作が失敗した場合、 Cドライバーは出力エラーを設定し、それ以上の操作を実行しません。

一括書き込み操作をカスタマイズ

オプション値を指定するBSONドキュメントを渡すことで、mongoc_collection_create_bulk_operation_with_opts() 関数の動作を変更できます。次の表では、ドキュメントで設定できるオプションについて説明します。

オプション	説明
`ordered`	`true` の場合、ドライバーは指定された順序で書き込み操作を実行します。エラーが発生した場合、残りの操作は試行されません。 `false` の場合、ドライバーは操作を任意の順序で実行し、すべての操作を実行しようとします。デフォルトは `true` です。
`writeConcern`	一括操作の書込み保証 (write concern)を指定します。詳細については、 MongoDB Serverマニュアルの「書込み保証」を参照してください。
`sessionId`	指定されたセッション内で一括操作を実行します。詳細については、 MongoDB Serverマニュアルの「サーバーセッション」を参照してください。
`comment`	操作にコメントを付けます。詳細については、 MongoDB Serverマニュアルの「削除コマンドフィールドのガイド」を参照してください。
`let`	操作の読みやすさを向上させるために、の値のリストを含むドキュメントを指定します。値は、ドキュメントフィールドを参照しない定数または閉じた式である必要があります。詳細については、 MongoDB Serverマニュアルの let ステートメントを参照してください。

次の例では、 mongoc_collection_create_bulk_operation_with_opts() 関数を呼び出し、ordered オプションを false に設定します。

bson_t opts;
BSON_APPEND_BOOL(&opts, "ordered", false);
bulk = mongoc_collection_create_bulk_operation_with_opts(collection, &opts);
// Perform bulk operation
bson_destroy(&opts);
mongoc_bulk_operation_destroy(bulk);

順序付けなし一括書き込み内のいずれかの書き込み操作が失敗した場合、 Cドライバーはすべての操作を試行した後にのみエラーを報告します。

注意

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

詳細情報

個々の書込み操作を実行する方法については、次のガイドを参照してください。

API ドキュメント

このガイドで説明した関数や型の詳細については、次のAPIドキュメントを参照してください。

戻る

削除

トランザクション