/ /

ドキュメントの置換

Overview

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

サンプルデータ

The examples in this guide use the restaurants collection in the sample_restaurants database from the Atlas sample datasets. To access this collection from your C++ application, instantiate a mongocxx::client that connects to an Atlas cluster and assign the following values to your db and collection variables:

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

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

置換操作

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

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

Query filter document: Specifies which document to replace. For more information about query filters, see Query Filter Documents in the MongoDB Server manual.
ドキュメントを置き換える : 新しいドキュメントに挿入するフィールドと値を指定します。

重要

_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`	Specifies whether the replace operation bypasses document validation. When set to `true`, this lets you replace a document with a new document that doesn't meet the schema validation requirements. For more information, see Schema Validation in the MongoDB Server manual. Defaults to `false`.
`collation`	Specifies the kind of language collation to use when sorting results. For more information, see Collation in the MongoDB Server manual.
`comment`	操作に添付する有効なBSONタイプのコメントを指定します。設定すると、このコメントは以下の場所にこのコマンドの記録と合わせて表示されます。 mongod log messages, in the `attr.command.cursor.comment` field Database profiler output, in the `system.profile.command` `comment` field `currentOp` output, in the `currentOp.command` `comment` field For more information, see the insert Command Fields guide in the MongoDB Server manual.
`hint`	Specifies the index to scan for documents that match the query filter. For more information, see the hint field in the MongoDB Server manual.
`let`	Specifies a document containing variables and their values to be used in the `replace_one()` method. This allows you to improve code readability by separating the variables from the operation text. Values must be constant or closed expressions that don't reference document fields. For more information, see the let field in the MongoDB Server manual.
`upsert`	クエリフィルターに一致するドキュメントがない場合に、置換操作でアップサート操作を実行するかどうかを指定します。デフォルトは `false` です。
`write_concern`	Sets the write concern for the operation. For more information, see Write Concern in the MongoDB Server manual.

例: ヒントオプション

次の例では、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;

例: 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

削除