/ /

ドキュメントの置換

Overview

このガイドでは、 C++ドライバーを使用してMongoDBコレクションに対して置換操作を実行する方法を学習できます。置換操作を実行すると、ターゲットドキュメント内の _idフィールドを除くすべてのフィールドが削除され、新しいフィールドに置き換えられます。単一のドキュメントを置き換えるには、replace_one() メソッドを呼び出します。

サンプルデータ

このガイドの例では、 Atlasサンプルデータセットのsample_restaurantsデータベースのrestaurantsコレクションを使用します。 C++アプリケーションからこのコレクションにアクセスするには、Atlasmongocxx::client クラスターに接続するをインスタンス化し、次の値をdb 変数とcollection 変数に割り当てます。

auto db = client["sample_restaurants"];
auto collection = db["restaurants"];

MongoDB Atlasクラスターを無料で作成して、サンプルデータセットをロードする方法については、MongoDBを使い始めるガイドを参照してください。

置換操作

replace_one() メソッドを呼び出すと置換操作を実行できます。このメソッドは、検索条件に一致する最初のドキュメントから _idフィールドを除くすべてのフィールドを削除します。次に、指定したフィールドと値がドキュメントに挿入されます。

replace_one() メソッドには次のパラメーターが必要です。

クエリフィルタードキュメント: 置き換えるドキュメントを指定します。クエリフィルターの詳細については、 MongoDB Serverマニュアルの「クエリフィルタードキュメント」を参照してください。
ドキュメントを置き換える : 新しいドキュメントに挿入するフィールドと値を指定します。

重要

_idフィールドの値は不変です。置き換えドキュメントで_idフィールドに値が指定される場合は、既存のドキュメントの_id値と一致する必要があります。

1 つのドキュメントの置き換えの例

次の例では、replace_one() メソッドを使用して、nameフィールドの値が "Nobu" のドキュメントを、nameフィールドの値が "La Bernadin" の新しいドキュメントに置き換えます。

auto query_filter = make_document(kvp("name", "Nobu"));
auto replace_doc = make_document(kvp("name", "La Bernadin"));
auto result = collection.replace_one(query_filter.view(), replace_doc.view());

ドキュメントが正常に置き換えられたかどうかを確認するには、find_one() メソッドを使用して新しいドキュメントを出力します。

auto new_doc = collection.find_one(make_document(kvp("name", "La Bernadin")));
std::cout << "New document: " << bsoncxx::to_json(*new_doc) << std::endl;

New document: { "_id" : { "$oid" : "..." }, "name" : "La Bernadin" }

find_one()メソッドの詳細については、データ取得ガイドの「 1 つのドキュメントの検索」を参照してください。

オプション

mongocxx::options::replaceクラスのインスタンスを任意の引数として渡すことで、replace_one() メソッドの動作を変更できます。次の表では、mongocxx::options::replaceインスタンスで設定できるフィールドを説明しています。

フィールド	説明
`bypass_document_validation`	置換操作がドキュメントの検証をバイパスするかどうかを指定します。`true` に設定すると、スキーマ検証要件を満たさないドキュメントを新しいドキュメントに置き換えることができます。詳細については、 MongoDB Serverマニュアルの「スキーマバリデーション」を参照してください。デフォルトは `false`です。
`collation`	結果をソートするときに使用する言語照合の種類を指定します。詳細については、MongoDB Server マニュアルの「照合」を参照してください。
`comment`	操作に添付する有効なBSONタイプのコメントを指定します。設定すると、このコメントは以下の場所にこのコマンドの記録と合わせて表示されます。 mongodログメッセージ、`attr.command.cursor.comment` フィールドデータベースプロファイラーの出力、`system.profile.commandcomment` フィールド `currentOpcurrentOp.commandcomment`フィールドの出力詳細については、 MongoDB Serverマニュアルの「コマンドフィールドの挿入」ガイドを参照してください。
`hint`	クエリフィルターに一致するドキュメントをスキャンするインデックスを指定します。詳細については、 MongoDB Serverマニュアルのヒントフィールドを参照してください。
`let`	`replace_one()` メソッドで使用する変数とその値を含むドキュメントを指定します。これにより、変数を操作テキストから分離して、コードの読みやすさを向上させることができます。値は、ドキュメントフィールドを参照しない定数または閉じた式である必要があります。詳細については、 MongoDB Serverマニュアルの letフィールドを参照してください。
`upsert`	クエリフィルターに一致するドキュメントがない場合に、置換操作でアップサート操作を実行するかどうかを指定します。デフォルトは `false`です。
`write_concern`	操作の書込み保証 (write concern)を設定します。詳細については、 MongoDB Serverマニュアルの「書込み保証」を参照してください。

例: ヒントオプション

次の例では、create_index() メソッドを使用して、nameフィールドに昇順の単一フィールドインデックスを作成しています。次に、hintフィールドを新しいインデックスに設定した後、mongocxx::options::replaceオブジェクトを replace_one() メソッドに渡します。これは、nameフィールドの値が "Nobu" であるドキュメントを置き換えるときに、nameフィールドインデックスを検索するように置換操作に指示します。

auto index_specification = make_document(kvp("name", 1));
collection.create_index(index_specification.view());
mongocxx::options::replace opts{}; 
opts.hint(mongocxx::hint{"name_1"});
auto query_filter = make_document(kvp("name", "Nobu"));
auto replace_doc = make_document(kvp("name", "La Bernadin"));
auto result = collection.replace_one(query_filter.view(), replace_doc.view(), opts);

インデックスの詳細については、「インデックスを使用したクエリの最適化」ガイドをご覧ください。

例: upsert オプション

次の例では、mongocxx::options::replaceオブジェクトの upsertフィールド値を true に設定して replace_one() メソッドに渡します。クエリフィルターに一致するドキュメントがないため、置換操作に、nameフィールドの値が "Shake Shack" である新しいドキュメントをコレクションに挿入するように指示します。

std::cout << "Total document count before replace_one(): " << collection.count_documents({}) << std::endl;
mongocxx::options::replace opts{}; 
opts.upsert(true);
auto query_filter = make_document(kvp("name", "In-N-Out Burger"));
auto replace_doc = make_document(kvp("name", "Shake Shack"));
auto result = collection.replace_one(query_filter.view(), replace_doc.view(), opts);
std::cout << "Total document count after replace_one(): " << collection.count_documents({}) << std::endl;

Total document count before replace_one(): 25359
Total document count after replace_one(): 25360

戻り値

replace_one() メソッドは mongocxx::result::replaceクラスのインスタンスを返します。このクラスには、次のメンバー関数が含まれています。

関数	説明
`matched_count()`	置き換えられたドキュメントの数に関係なく、クエリフィルターに一致したドキュメントの数を返します。
`modified_count()`	置換操作によって変更されたドキュメントの数を返します。置換されたドキュメントが元と同一の場合、このカウントには含まれません。
`result()`	操作の一括書込み (write) 結果を返します。
`upserted_id()`	ドライバーがアップサートを実行した場合、データベースでアップサートされたドキュメントのIDを返します。

例:matched_count()

次の例では、replace_one() メソッドを使用して、nameフィールドの値が "Shake Shack" のドキュメントを、nameフィールドの値が "In-N-Out Burger" の新しいドキュメントに置き換えます。次に、matched_count() メンバー関数を呼び出して、クエリフィルターに一致するドキュメントの数を出力します。

auto query_filter = make_document(kvp("name", "Shake Shack"));
auto replace_doc = make_document(kvp("name", "In-N-Out Burger"));
auto result = collection.replace_one(query_filter.view(), replace_doc.view());
std::cout << "Matched documents: " << result->matched_count() << std::endl;

Matched documents: 11

例: upserted_id()

次の例では、replace_one() メソッドを使用して、nameフィールドの値が "In-N-Out Burger" であるドキュメントを置き換えます。upsert オプションが true に設定されているため、クエリフィルターが既存のドキュメントと一致しない場合、 C++ドライバーは新しいドキュメントを挿入します。次に、コードは upserted_id() メンバー関数を呼び出して、アップサートされたドキュメントの _idフィールド値を出力します。

mongocxx::options::replace opts{}; 
opts.upsert(true);
auto query_filter = make_document(kvp("name", "In-N-Out Burger"));
auto replace_doc = make_document(kvp("name", "Shake Shack"));
auto result = collection.replace_one(query_filter.view(), replace_doc.view(), opts);
auto id = result->upserted_id()->get_value();
        
std::cout << "Upserted ID: " << id.get_oid().value.to_string() << std::endl;

// Your ID value may differ
Upserted ID: 67128c5ecc1f8c15ea26fcf8

詳細情報

クエリフィルターの作成の詳細については、「クエリの指定」ガイドを参照してください。

API ドキュメント

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

戻る

Update

削除