/ /

复合运算符

Overview

在本指南中，您可以了解如何使用 Rust 驱动程序执行复合操作。

复合操作将读取和写入操作的功能组合成一个原子动作。如果您按顺序执行读取操作和写入操作，有人可能会在操作之间更改您的目标文档，从而导致意外结果。当您执行复合操作时， MongoDB会在您正在修改的文档上放置写锁（write lock），直到操作完成，从而防止中间数据更改。

您可以使用驱动程序执行以下复合操作：

查找并删除一个文档
查找并更新一个文档
查找并替换一个文档

本指南包括以下部分：

示例的样本数据显示复合操作示例使用的样本数据
查找和删除文档描述了如何在单个操作中查找和删除文档
查找和更新文档描述了如何在单个操作中查找和更新文档
查找和替换文档描述了如何在单个操作中查找和替换文档
附加信息提供了本指南中提到的类型和方法的资源和 API 文档链接

提示

要了解如何一次对多个文档执行原子读写操作，请参阅事务指南。

示例样本数据

本指南中的示例使用以下样本文档。每个文档代表一名学生，并包含有关他们的年龄和就读学校的信息：

{ "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()方法的行为。要为每个设置使用默认值，请为 options 参数指定值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`	与操作绑定的任意 `Bson` 值，可通过数据库分析器、`currentOp` 和日志进行追踪。此选项仅在连接到 MongoDB Server 4.4 及更高版本时可用。类型：`Bson` 默认：`None`

Rust 驱动程序实现了用于创建FindOneAndDeleteOptions实例的 Builder 设计模式。您可以使用该类型的builder()方法，通过逐个链接选项构建器函数来构造选项实例。

以下代码显示如何构造 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()方法的行为。要为每个设置使用默认值，请为 options 参数指定值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`	与操作绑定的任意 `Bson` 值，可通过数据库分析器、`currentOp` 和日志进行追踪。此选项仅在连接到 MongoDB Server 4.4 及更高版本时可用。类型：`Bson` 默认：`None`

Rust 驱动程序实现了用于创建FindOneAndUpdateOptions实例的 Builder 设计模式。您可以使用该类型的builder()方法，通过逐个链接选项构建器方法来构造选项实例。

以下代码显示如何构造 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()方法的行为。要为每个设置使用默认值，请为 options 参数指定值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`	与操作绑定的任意 `Bson` 值，可通过数据库分析器、`currentOp` 和日志进行追踪。此选项仅在连接到 MongoDB Server 4.4 及更高版本时可用。类型：`Bson` 默认：`None`

Rust 驱动程序实现了用于创建FindOneAndReplaceOptions实例的 Builder 设计模式。您可以使用该类型的builder()方法，通过逐个链接选项构建器函数来构造选项实例。

以下代码显示如何构造 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()方法：

查询过滤器，用于匹配 name 的值包含字符串 "Johnson" 的文档
描述新学生的替换文档
一个实例FindOneAndReplaceOptions，它在替换后返回文档，并仅在输出中的项目name和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")}))