/ /

複合演算子

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で利用できるオプションについて説明しています。

オプション	説明
`max_time`	クエリが実行する最大時間（ミリ秒単位）。タイプ: `Duration`
`projection`	結果を返すときに使用するプロジェクション。タイプ: `Document` デフォルト: `None`
`sort`	The sorting order to use when returning results. By default, the driver returns documents in their natural order, or as they appear in the database. To learn more, see natural order in the Server manual glossary. Type: `Document` Default: `None`
`write_concern`	The write concern for the operation. If you don't set this option, the operation inherits the write concern set for the collection. To learn more about write concerns, see Write Concern in the Server manual. Type: `WriteConcern`
`collation`	結果をソートするときに使用する照合。照合について詳しくは、「照合」ガイドを参照してください。タイプ: `Collation` デフォルト: `None`
`hint`	操作に使用するインデックス。インデックスの詳細については、サーバーマニュアルの「インデックス」を参照してください。このオプションは、 MongoDB Serverバージョン.4 4 以降に接続している場合にのみ使用できます。タイプ:`Hint` デフォルト:`None`
`let_vars`	パラメーターと値のマップ。これらのパラメーターには、集計式の変数としてアクセスできます。このオプションは、MongoDB Server バージョン 5.0 以降に接続する場合にのみ利用できます。タイプ: `Document`
`comment`	データベースプロファイラー、`currentOp`、およびログを介して操作をトレースするための任意の `Bson` 値。このオプションは、MongoDB Server バージョン 4.4 以降に接続した場合にのみ使用できます。タイプ: `Bson` デフォルト: `None`

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);

Deleted document:
Some(Document({"_id": ObjectId("..."),
"name": String("Deanna Porowski"), "age": Int32(10), "school":
String("Lakeside Elementary")}))

ドキュメントの検索と更新

find_one_and_update()メソッドは、指定されたクエリフィルターに一致する最初のドキュメントを検索してアップデートします。この操作では、更新ドキュメントで指定した仕様に基づいてドキュメントが更新されます。ドキュメントがフィルタ条件に一致する場合、メソッドはSomeタイプを返します。一致するドキュメントがない場合は、 Noneタイプが返されます。

注意

ドキュメントの検索と更新の間に他の操作を実行する場合は、 find_one()メソッドを呼び出し、その後にupdate_one()メソッドを呼び出します。

検索と更新の動作を変更する

オプションで、 FindOneAndUpdateOptionsインスタンスをパラメータとして渡すことで、 find_one_and_update()メソッドの動作を変更できます。各設定でデフォルト値を使用するには、オプションパラメータに値Noneを指定します。

次の表では、 FineOneAndDeleteOptionsで利用できるオプションについて説明しています。

オプション	説明
`array_filters`	更新を適用する配列要素を指定するフィルターのセット。タイプ: `Vec<Document>`
`bypass_document_validation`	If `true`, allows the driver to perform a write that violates document-level validation. To learn more about validation, see Schema Validation in the Server manual. Type: `bool` Default: `false`
`max_time`	クエリが実行する最大時間（ミリ秒単位）。タイプ: `Duration`
`projection`	結果を返すときに使用するプロジェクション。タイプ: `Document` デフォルト: `None`
`return_document`	`Before` の場合、操作は更新前のドキュメントを返します。`After` の場合、操作は更新されたドキュメントを返します。タイプ: `ReturnDocument` デフォルト: `ReturnDocument::Before`
`sort`	The sorting order to use when returning results. By default, the driver returns documents in their natural order, or as they appear in the database. To learn more, see natural order in the Server manual glossary. Type: `Document` Default: `None`
`upsert`	true の場合、クエリフィルターに一致するドキュメントがない場合、操作によってドキュメントが挿入されます。タイプ: `bool` デフォルト: `false`
`write_concern`	The write concern for the operation. If you don't set this option, the operation inherits the write concern set for the collection. To learn more about write concerns, see Write Concern in the Server manual. Type: `WriteConcern`
`collation`	結果をソートするときに使用する照合。照合について詳しくは、「照合」ガイドを参照してください。タイプ: `Collation` デフォルト: `None`
`hint`	The index to use for the operation. To learn more about indexes, see Indexes in the Server manual. This option is available only when connecting to MongoDB Server versions 4.4 and later. Type: `Hint` Default: `None`
`let_vars`	パラメーターと値のマップ。これらのパラメーターには、集計式の変数としてアクセスできます。このオプションは、MongoDB Server バージョン 5.0 以降に接続する場合にのみ利用できます。タイプ: `Document`
`comment`	データベースプロファイラー、`currentOp`、およびログを介して操作をトレースするための任意の `Bson` 値。このオプションは、MongoDB Server バージョン 4.4 以降に接続した場合にのみ使用できます。タイプ: `Bson` デフォルト: `None`

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);

Updated document:
Some(Document({"_id": ObjectId("..."),
"name": String("Ben Joseph"), "age": Int32(17), "school":
String("Durango High School")}))

ドキュメントの検索と置換

find_one_and_replace()メソッドは、指定されたクエリフィルターに一致する最初のドキュメントを検索して置き換えます。この操作により、 _idフィールドを除くドキュメントのすべてのフィールドが、指定したフィールドと値に置き換えられます。ドキュメントがフィルタ条件に一致する場合、メソッドはSome型を返します。一致するドキュメントがない場合は、 Noneタイプが返されます。

注意

ドキュメントの検索と置換の間に他の操作を実行する場合は、 find_one()メソッド、その後にreplace_one()メソッドを呼び出します。

検索と置換の動作を変更する

オプションで、 FindOneAndReplaceOptionsインスタンスをパラメータとして渡すことで、 find_one_and_replace()メソッドの動作を変更できます。各設定でデフォルト値を使用するには、オプションパラメータに値Noneを指定します。

次の表では、 FindOneAndReplaceOptionsで利用できるオプションについて説明しています。

オプション	説明
`bypass_document_validation`	If `true`, allows the driver to perform a write that violates document-level validation. To learn more about validation, see Schema Validation in the Server manual. Type: `bool` Default: `false`
`max_time`	クエリが実行する最大時間（ミリ秒単位）。タイプ: `Duration`
`projection`	結果を返すときに使用するプロジェクション。タイプ: `Document` デフォルト: `None`
`return_document`	`Before` の場合、操作は更新前のドキュメントを返します。`After` の場合、操作は更新されたドキュメントを返します。タイプ: `ReturnDocument` デフォルト: `ReturnDocument::Before`
`sort`	The sorting order to use when returning results. By default, the driver returns documents in their natural order, or as they appear in the database. To learn more, see natural order in the Server manual glossary. Type: `Document` Default: `None`
`upsert`	true の場合、クエリフィルターに一致するドキュメントがない場合、操作によってドキュメントが挿入されます。タイプ: `bool` デフォルト: `false`
`write_concern`	The write concern for the operation. If you don't set this option, the operation inherits the write concern set for the collection. To learn more about write concerns, see Write Concern in the Server manual. Type: `WriteConcern`
`collation`	結果をソートするときに使用する照合。照合について詳しくは、「照合」ガイドを参照してください。タイプ: `Collation` デフォルト: `None`
`hint`	The index to use for the operation. To learn more about indexes, see Indexes in the Server manual. This option is available only when connecting to MongoDB Server versions 4.4 and later. Type: `Hint` Default: `None`
`let_vars`	パラメーターと値のマップ。これらのパラメーターには、集計式の変数としてアクセスできます。このオプションは、MongoDB Server バージョン 5.0 以降に接続する場合にのみ利用できます。タイプ: `Document`
`comment`	データベースプロファイラー、`currentOp`、およびログを介して操作をトレースするための任意の `Bson` 値。このオプションは、MongoDB Server バージョン 4.4 以降に接続した場合にのみ使用できます。タイプ: `Bson` デフォルト: `None`

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);

Document after replacement:
Some(Document({"name": String("Toby Fletcher"), "school":
String("Durango High School")}))

詳細情報

このガイドの操作の詳細については、次のドキュメントを参照してください。

API ドキュメント

このガイドで言及されているメソッドとタイプの詳細については、次のAPIドキュメントを参照してください。

戻る

一括操作

直列化