ドキュメントの置換
Overview
このガイドでは、 C++ドライバーを使用してMongoDBコレクションに対して置換操作を実行する方法を学習できます。置換操作を実行すると、ターゲットドキュメント内の _idフィールドを除くすべてのフィールドが削除され、新しいフィールドに置き換えられます。単一のドキュメントを置き換えるには、replace_one() メソッドを呼び出します。
サンプル データ
このガイドの例では、 Atlasサンプルデータセットのsample_restaurantsデータベースのrestaurantsコレクションを使用します。 C++アプリケーションからこのコレクションにアクセスするには、Atlasmongocxx::client クラスターに接続する をインスタンス化し、 変数と 変数に次の値を割り当てます。dbcollection
auto db = client["sample_restaurants"]; auto collection = db["restaurants"];
MongoDB Atlasクラスターを無料で作成して、サンプルデータセットをロードする方法については、 「Atlas を使い始める」ガイドを参照してください。
置換操作
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 | 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 | Specifies a comment of any valid BSON type to attach to the operation.
Once set, this comment appears alongside records of this command in the following locations:
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 | Specifies whether the replace operation performs an upsert operation if no
documents match the query filter. Defaults to 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() | Returns the number of documents that matched the query filter, regardless of
how many were replaced. |
modified_count() | Returns number of documents modified by the replace operation. If a replaced
document is identical to the original, it is not included in this
count. |
result() | Returns the bulk write result for the operation. |
upserted_id() | Returns the ID of the document that was upserted in the database, if the driver
performed an upsert. |
例: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 ドキュメントを参照してください。