/ /

複合演算子

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()メソッドを呼び出します。

検索と削除の動作を変更する

オプションで、オプションビルダーメソッドをfind_one_and_delete()に連鎖させることで、 find_one_and_delete()メソッドの動作を変更できます。これらのビルダーメソッドはFindOneAndDeleteOptions構造体フィールドを設定します。

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

オプション	説明
`max_time`	クエリが実行する最大時間（ミリ秒単位）。タイプ: `Duration`
`projection`	結果を返すときに使用するプロジェクション。タイプ: `Document` デフォルト: `None`
`sort`	結果を返す際に使用するソート順序。デフォルトでは、ドライバーはドキュメントを自然な順序、つまりデータベースに表示される順序で返します。詳細については、サーバーマニュアルの用語集にある自然な順序を参照してください。型: `Document` デフォルト: `None`
`write_concern`	操作の書込み保証 (write concern)。このオプションを設定しない場合、操作はコレクションに設定された書込み保証 (write concern)を継承します。書込み保証 (write concern) の詳細については、サーバーマニュアルの「書込み保証(write concern) 」を参照してください。タイプ: `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`

注意

設定オプション

オプションビルダのメソッドをfind_one_and_delete()メソッド呼び出しに直接連鎖させることで、 FindOneAndDeleteOptionsフィールドを設定できます。以前のバージョンのドライバーを使用している場合は、オプションビルダーメソッドをbuilder()メソッドに連結してFindOneAndDeleteOptionsインスタンスを構築する必要があります。次に、オプションインスタンスをパラメーターとしてfind_one_and_delete()に渡します。

次のコードは、 comment()メソッドをfind_one_and_delete()メソッドに連結してcommentフィールドを設定する方法を示しています。

let res = my_coll.find_one_and_delete(filter)
    .comment(bson!("hello"))
    .await?;

検索と削除の例

次の例では、 find_one_and_delete()メソッドを使用して、 ageフィールドの値が10以下の最初のドキュメントを検索して削除します。

let filter = doc! { "age": doc! { "$lte": 10 } };
let res = my_coll.find_one_and_delete(filter).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()メソッドを呼び出します。

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

オプションで、オプションビルダーメソッドをfind_one_and_update()に連鎖させることで、 find_one_and_update()メソッドの動作を変更できます。これらのビルダーメソッドはFindOneAndUpdateOptions構造体フィールドを設定します。

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

オプション	説明
`array_filters`	更新が適用される配列要素を指定するフィルターのセット。詳細については、「ドキュメント内の配列の更新」ガイドを参照してください。タイプ: `Vec<Document>`
`bypass_document_validation`	`true` の場合、ドライバーはドキュメントレベルの検証に違反する書き込み (write) を実行できます。検証の詳細については、サーバーマニュアルの「スキーマ検証」を参照してください。タイプ: `bool` デフォルト: `false`
`max_time`	クエリが実行する最大時間（ミリ秒単位）。タイプ: `Duration`
`projection`	結果を返すときに使用するプロジェクション。タイプ: `Document` デフォルト: `None`
`return_document`	`Before` の場合、操作は更新前のドキュメントを返します。`After` の場合、操作は更新されたドキュメントを返します。タイプ: `ReturnDocument` デフォルト: `ReturnDocument::Before`
`sort`	結果を返す際に使用するソート順序。デフォルトでは、ドライバーはドキュメントを自然な順序、つまりデータベースに表示される順序で返します。詳細については、サーバーマニュアルの用語集にある自然な順序を参照してください。型: `Document` デフォルト: `None`
`upsert`	true の場合、クエリフィルターに一致するドキュメントがない場合、操作によってドキュメントが挿入されます。タイプ: `bool` デフォルト: `false`
`write_concern`	操作の書込み保証 (write concern)。このオプションを設定しない場合、操作はコレクションに設定された書込み保証 (write concern)を継承します。書込み保証 (write concern) の詳細については、サーバーマニュアルの「書込み保証(write concern) 」を参照してください。タイプ: `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`

次のコードは、 comment()メソッドをfind_one_and_update()メソッドに連結してcommentフィールドを設定する方法を示しています。

let res = my_coll.find_one_and_update(filter, update)
    .comment(bson!("hello"))
    .await?;

検索と更新の例

この例では、次のアクションを実行する方法を示しています。

find_one_and_update()メソッドを呼び出す
schoolの値が"Aurora High School"であるドキュメントに一致するクエリフィルターをfind_one_and_update()に渡す
アップデートドキュメントをfind_one_and_update()に渡します。これで、 schoolフィールドを"Durango High School"に設定し、 ageフィールドを1ずつ増加させます
更新後に一致したドキュメントを返すには、 return_document()メソッドをfind_one_and_update()にチェーンします

let filter = doc! { "school": "Aurora High School" };
let update =
    doc! { "$set": doc! { "school": "Durango High School" },
           "$inc": doc! { "age": 1 } };
let res = my_coll.find_one_and_update(filter, update)
    .return_document(ReturnDocument::After)
    .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()メソッドを呼び出します。

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

オプションで、オプションビルダーメソッドをfind_one_and_replace()に連鎖させることで、 find_one_and_replace()メソッドの動作を変更できます。これらのビルダーメソッドはFindOneAndReplaceOptions構造体フィールドを設定します。

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

オプション	説明
`bypass_document_validation`	`true` の場合、ドライバーはドキュメントレベルの検証に違反する書き込み (write) を実行できます。検証の詳細については、サーバーマニュアルの「スキーマ検証」を参照してください。タイプ: `bool` デフォルト: `false`
`max_time`	クエリが実行する最大時間（ミリ秒単位）。タイプ: `Duration`
`projection`	結果を返すときに使用するプロジェクション。タイプ: `Document` デフォルト: `None`
`return_document`	`Before` の場合、操作は更新前のドキュメントを返します。`After` の場合、操作は更新されたドキュメントを返します。タイプ: `ReturnDocument` デフォルト: `ReturnDocument::Before`
`sort`	結果を返す際に使用するソート順序。デフォルトでは、ドライバーはドキュメントを自然な順序、つまりデータベースに表示される順序で返します。詳細については、サーバーマニュアルの用語集にある自然な順序を参照してください。型: `Document` デフォルト: `None`
`upsert`	true の場合、クエリフィルターに一致するドキュメントがない場合、操作によってドキュメントが挿入されます。タイプ: `bool` デフォルト: `false`
`write_concern`	操作の書込み保証 (write concern)。このオプションを設定しない場合、操作はコレクションに設定された書込み保証 (write concern)を継承します。書込み保証 (write concern) の詳細については、サーバーマニュアルの「書込み保証(write concern) 」を参照してください。タイプ: `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`

次のコードは、 comment()メソッドをfind_one_and_replace()メソッドに連結してcommentフィールドを設定する方法を示しています。

let res = my_coll.find_one_and_replace(filter, replacement)
    .comment(bson!("hello"))
    .await?;

検索と置換の例

この例では、次のアクションを実行します。

find_one_and_replace()メソッドを呼び出します
nameの値に string が含まれるドキュメントに一致するクエリフィルターをfind_one_and_replace() "Johnson"渡します
新しい学生を説明する置換ドキュメントをfind_one_and_replace()に渡します
置換後にドキュメントを返すには、 return_document()メソッドをfind_one_and_replace()にチェーンします
メソッドを出力のフィールドとフィールドにチェーンしますprojection()find_one_and_replace()``to project only the ``nameschool

let filter = doc! { "name": doc! { "$regex": "Johnson" } };
let replacement =
    doc! { "name": "Toby Fletcher", 
           "age": 14,
           "school": "Durango High School" };
let res = my_coll.find_one_and_replace(filter, replacement)
    .return_document(ReturnDocument::After)
    .projection(doc! { "name": 1, "school": 1, "_id": 0 })
    .await?;
println!("Document after replacement:\n{:?}", res);

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

詳細情報

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

API ドキュメント

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

戻る

トランザクション

CRUD操作の構成