Overview
このガイドでは、Rust ドライバーを使用して複合操作を実行する方法を説明します。
複合操作は、読み取り操作と書込み (write) 操作の機能を 1 つのアトミックアクションに結合します。 読み取り操作と書込み操作を順番に実行すると、操作の間にターゲット ドキュメントが変更される可能性があり、予期しない結果につながる恐れがあります。 複合操作を実行する場合、MongoDB は操作が完了するまで変更しているドキュメントに書込みロック (write lock) を適用して中間データの変更を防ぎます。
ドライバーを使用して次の複合操作を実行できます。
1 つのドキュメントを検索して削除
1 つのドキュメントを検索して更新
1 つのドキュメントを検索して置換
このガイドには、次のセクションが含まれています。
例のサンプル データ では、複合操作の例で使用されるサンプル データが
「ドキュメントの検索と削除」では、1 回の操作でドキュメントを検索して削除する方法について説明します
ドキュメントの検索と更新では、1 回の操作でドキュメントを検索して更新する方法について説明します
「ドキュメントの検索と置換」では、1 回の操作でドキュメントを検索して置換する方法について説明します
追加情報では、このガイドで言及されている型とメソッドのリソースとAPIドキュメントへのリンクを提供します
Tip
一度に複数のドキュメントに対してアトミックな読み取りおよび書込み操作を実行する方法については、トランザクションガイドを参照してください。
サンプルデータの例
このガイドの例では、次のサンプル ドキュメントを使用します。 各ドキュメントは学生を表し、その名前の詳細と所属するデータベースに関する情報が含まれています。
{ "name": "Alex Johnson", "age": 8, "school": "Lakeside Elementary" },{ "name": "Samara Khan", "age": 11, "school": "Rolling Hills Middle School" },{ "name": "Ben Joseph", "age": 16, "school": "Aurora High School" },{ "name": "Deanna Porowski", "age": 10, "school": "Lakeside Elementary" }ドキュメントの検索と削除
find_one_and_delete()メソッドは、指定されたクエリフィルターに一致する最初のドキュメントを検索して削除します。 ドキュメントがフィルタ条件に一致する場合、メソッドはSomeタイプを返します。 一致するドキュメントがない場合は、 Noneタイプが返されます。
注意
ドキュメントの検索と削除の間に他の操作を実行する場合は、 find_one()メソッドを呼び出し、その後にdelete_one()メソッドを呼び出します。
検索と削除の動作を変更する
オプションで、 FineOneAndDeleteOptionsインスタンスをパラメータとして渡すことで、 find_one_and_delete()メソッドの動作を変更できます。 各設定でデフォルト値を使用するには、オプション パラメータに値Noneを指定します。
次の表では、 FineOneAndDeleteOptionsで利用できるオプションについて説明しています。
オプション | 説明 |
|---|---|
| クエリが実行する最大時間(ミリ秒単位)。 |
| 結果を返すときに使用するプロジェクション。 |
| 結果を返す際に使用するソート順序。デフォルトでは、ドライバーはドキュメントを自然な順序、つまりデータベースに表示される順序で返します。詳細については、サーバー マニュアルの用語集にある自然な順序を参照してください。 |
| 操作の書込み保証 (write concern)。このオプションを設定しない場合、操作はコレクションに設定された書込み保証 (write concern)を継承します。書込み保証 (write concern) の詳細については、サーバー マニュアルの「書込み保証(write concern) 」を参照してください。 |
| 結果をソートするときに使用する照合。照合について詳しくは、「照合」ガイドを参照してください。 |
| 操作に使用するインデックス。インデックスの詳細については、サーバー マニュアルの「インデックス」を参照してください。このオプションは、MongoDB Server バージョン 4.4 以降に接続した場合にのみ使用できます。 |
| パラメーターと値のマップ。これらのパラメーターには、集計式の変数としてアクセスできます。このオプションは、MongoDB Server バージョン 5.0 以降に接続する場合にのみ利用できます。 |
| データベースプロファイラー、 |
Rust ドライバーは、 FindOneAndDeleteOptionsインスタンスを作成するためのビルダ設計パターンを実装します。 タイプのbuilder()メソッドを使用して、オプション ビルダー関数を 1 つずつ連鎖させてオプション インスタンスを構築できます。
次のコードは、 FindOneAndDeleteOptionsインスタンスを構築し、それをfind_one_and_delete()メソッドに渡す方法を示しています。
let opts = FindOneAndDeleteOptions::builder().comment(bson!("hello")).build();let res = my_coll.find_one_and_delete(filter, opts).await?;検索と削除の例
次の例では、 find_one_and_delete()メソッドを使用して、 ageフィールドの値が10以下の最初のドキュメントを検索して削除します。
let filter = doc! { "age": doc! { "$lte": 10 } };
let res = my_coll.find_one_and_delete(filter, None).await?;println!("Deleted document:\n{:?}", res);ドキュメントの検索と更新
find_one_and_update()メソッドは、指定されたクエリフィルターに一致する最初のドキュメントを検索してアップデートします。 この操作では、更新ドキュメントで指定した仕様に基づいてドキュメントが更新されます。 ドキュメントがフィルタ条件に一致する場合、メソッドはSomeタイプを返します。 一致するドキュメントがない場合は、 Noneタイプが返されます。
注意
ドキュメントの検索と更新の間に他の操作を実行する場合は、 find_one()メソッドを呼び出し、その後にupdate_one()メソッドを呼び出します。
検索と更新の動作を変更する
オプションで、 FindOneAndUpdateOptionsインスタンスをパラメータとして渡すことで、 find_one_and_update()メソッドの動作を変更できます。 各設定でデフォルト値を使用するには、オプション パラメータに値Noneを指定します。
次の表では、 FineOneAndDeleteOptionsで利用できるオプションについて説明しています。
オプション | 説明 |
|---|---|
| 更新を適用する配列要素を指定するフィルターのセット。 |
|
|
| クエリが実行する最大時間(ミリ秒単位)。 |
| 結果を返すときに使用するプロジェクション。 |
|
|
| 結果を返す際に使用するソート順序。デフォルトでは、ドライバーはドキュメントを自然な順序、つまりデータベースに表示される順序で返します。詳細については、サーバー マニュアルの用語集にある自然な順序を参照してください。 |
| true の場合、クエリフィルターに一致するドキュメントがない場合、操作によってドキュメントが挿入されます。 |
| 操作の書込み保証 (write concern)。このオプションを設定しない場合、操作はコレクションに設定された書込み保証 (write concern)を継承します。書込み保証 (write concern) の詳細については、サーバー マニュアルの「書込み保証(write concern) 」を参照してください。 |
| 結果をソートするときに使用する照合。照合について詳しくは、「照合」ガイドを参照してください。 |
| 操作に使用するインデックス。インデックスの詳細については、サーバー マニュアルの「インデックス」を参照してください。このオプションは、MongoDB Server バージョン 4.4 以降に接続した場合にのみ使用できます。 |
| パラメーターと値のマップ。これらのパラメーターには、集計式の変数としてアクセスできます。このオプションは、MongoDB Server バージョン 5.0 以降に接続する場合にのみ利用できます。 |
| データベースプロファイラー、 |
Rust ドライバーは、 FindOneAndUpdateOptionsインスタンスを作成するためのビルダ設計パターンを実装します。 タイプのbuilder()メソッドを使用して、オプション ビルダー メソッドを 1 つずつ連鎖させてオプション インスタンスを構築できます。
次のコードは、 FindOneAndUpdateOptionsインスタンスを構築し、それをfind_one_and_update()メソッドに渡す方法を示しています。
let opts = FindOneAndUpdateOptions::builder().comment(bson!("hello")).build();let res = my_coll.find_one_and_update(filter, update, opts).await?;検索と更新の例
以下の例では、次のパラメータを使用してfind_one_and_update()メソッドを呼び出す方法を示しています。
schoolの値が"Aurora High School"であるドキュメントに一致するクエリフィルターschoolフィールドを"Durango High School"に設定し、ageフィールドを1ずつ増加させる更新ドキュメント更新後にドキュメントを返す
FindOneAndUpdateOptionsインスタンス
let filter = doc! { "school": "Aurora High School" };let update = doc! { "$set": doc! { "school": "Durango High School" }, "$inc": doc! { "age": 1 } };let opts = FindOneAndUpdateOptions::builder() .return_document(Some(ReturnDocument::After)) .build();
let res = my_coll.find_one_and_update(filter, update, opts).await?;println!("Updated document:\n{:?}", res);ドキュメントの検索と置換
find_one_and_replace()メソッドは、指定されたクエリフィルターに一致する最初のドキュメントを検索して置き換えます。 この操作により、 _idフィールドを除くドキュメントのすべてのフィールドが、指定したフィールドと値に置き換えられます。 ドキュメントがフィルタ条件に一致する場合、メソッドはSome型を返します。 一致するドキュメントがない場合は、 Noneタイプが返されます。
注意
ドキュメントの検索と置換の間に他の操作を実行する場合は、 find_one()メソッド、その後にreplace_one()メソッドを呼び出します。
検索と置換の動作を変更する
オプションで、 FindOneAndReplaceOptionsインスタンスをパラメータとして渡すことで、 find_one_and_replace()メソッドの動作を変更できます。 各設定でデフォルト値を使用するには、オプション パラメータに値Noneを指定します。
次の表では、 FindOneAndReplaceOptionsで利用できるオプションについて説明しています。
オプション | 説明 |
|---|---|
|
|
| クエリが実行する最大時間(ミリ秒単位)。 |
| 結果を返すときに使用するプロジェクション。 |
|
|
| 結果を返す際に使用するソート順序。デフォルトでは、ドライバーはドキュメントを自然な順序、つまりデータベースに表示される順序で返します。詳細については、サーバー マニュアルの用語集にある自然な順序を参照してください。 |
| true の場合、クエリフィルターに一致するドキュメントがない場合、操作によってドキュメントが挿入されます。 |
| 操作の書込み保証 (write concern)。このオプションを設定しない場合、操作はコレクションに設定された書込み保証 (write concern)を継承します。書込み保証 (write concern) の詳細については、サーバー マニュアルの「書込み保証(write concern) 」を参照してください。 |
| 結果をソートするときに使用する照合。照合について詳しくは、「照合」ガイドを参照してください。 |
| 操作に使用するインデックス。インデックスの詳細については、サーバー マニュアルの「インデックス」を参照してください。このオプションは、MongoDB Server バージョン 4.4 以降に接続した場合にのみ使用できます。 |
| パラメーターと値のマップ。これらのパラメーターには、集計式の変数としてアクセスできます。このオプションは、MongoDB Server バージョン 5.0 以降に接続する場合にのみ利用できます。 |
| データベースプロファイラー、 |
Rust ドライバーは、 FindOneAndReplaceOptionsインスタンスを作成するためのビルダ設計パターンを実装します。 タイプのbuilder()メソッドを使用して、オプション ビルダー関数を 1 つずつ連鎖させてオプション インスタンスを構築できます。
次のコードは、 FindOneAndReplaceOptionsインスタンスを構築し、それをfind_one_and_replace()メソッドに渡す方法を示しています。
let opts = FindOneAndReplaceOptions::builder().comment(bson!("hello")).build();let res = my_coll.find_one_and_replace(filter, replacement, opts).await?;検索と置換の例
以下の例では、次のパラメータを使用してfind_one_and_replace()メソッドを呼び出す方法を示しています。
"Johnson"nameの値に string が含まれるドキュメントに一致するクエリフィルター新しい学生を説明する置換ドキュメント
FindOneAndReplaceOptionsname置換後にドキュメントを返し、出力のschoolフィールドと フィールドのみをプロジェクションする インスタンス
let filter = doc! { "name": doc! { "$regex": "Johnson" } };let replacement = doc! { "name": "Toby Fletcher", "age": 14, "school": "Durango High School" };let opts = FindOneAndReplaceOptions::builder() .return_document(Some(ReturnDocument::After)) .projection(doc! { "name": 1, "school": 1, "_id": 0 }) .build();
let res = my_coll.find_one_and_replace(filter, replacement, opts).await?;println!("Document after replacement:\n{:?}", res);詳細情報
このガイドの操作の詳細については、次のドキュメントを参照してください。
API ドキュメント
このガイドで言及されているメソッドとタイプの詳細については、次のAPIドキュメントを参照してください。