/ /

/ /

替换文档

Overview

在本指南中，您可以学习如何使用Rust驱动程序通过 replace_one() 方法替换MongoDB集合中的文档。

替换操作会删除文档中除 _id 字段之外的所有现有字段，并用新的字段和值替换删除的字段。

注意

要学习；了解如何更新文档中的特定字段，请参阅更新文档指南。

本指南包括以下部分：

替换文档描述了如何使用驱动程序执行替换操作
修改替换行为描述了如何修改 replace_one() 方法的默认行为
附加信息提供了本指南中提到的类型和方法的资源和 API 文档链接

_id 字段

MongoDB集合中的每个文档都有一个唯一且不可变的 _id字段。如果您尝试通过替换操作更改 _id字段，驱动程序将引发 WriteError 并且不会执行更新。

替换文档

您可以使用 replace_one() 方法执行替换操作。此方法会删除文档中除 _id字段之外的所有现有字段，并用您指定的新字段和值替换已删除的字段。

您还可以将选项构建者方法链接到 replace_one() 方法。若要学习；了解如何修改此方法的行为，请参阅本指南的“修改替换行为”部分。

提示

您可以使用复合操作在一个操作中检索和修改数据。要了解更多信息，请参阅复合操作指南。

参数

replace_one() 方法采用以下参数：

查询筛选条件以匹配要替换的文档
替换文档，其中包含将替换现有文档的字段和值

替换文档使用以下格式：

doc! { "<field>": <value>, "<field>": <value>, ... }

返回值

如果操作成功， replace_one()方法会返回UpdateResult类型。 UpdateResult类型包含以下描述操作的属性：

属性	说明
`matched_count`	过滤匹配的文档数
`modified_count`	操作修改的文档数量
`upserted_id`	更新或插入文档的 `_id`，如果没有则为空

如果多个文档与您传递给replace_one()的查询筛选器匹配，则该方法会选择并替换第一个匹配的文档。如果没有与查询筛选器匹配的文档，则替换操作不会进行任何更改。

示例

本部分提供的示例演示如何使用 replace_one() 方法替换集合中的文档。

替换示例

以下文档描述了某公司的一名员工：

{
  "_id": ObjectId('4501'),
  "name": "Matt DeGuy",
  "role": "Consultant",
  "team_members": [ "Jill Gillison", "Susan Lee" ]
}

此示例使用replace_one()方法将前面的文档替换为具有以下字段的文档：

name值为"Susan Lee"
role值为"Lead Consultant"
team_members值为[ "Jill Gillison" ]

let replace_doc = doc! {
    "name": "Susan Lee",
    "role": "Lead Consultant",
    "team_members": vec! [ "Jill Gillison" ]
};
let res = my_coll
    .replace_one(doc! { "name": "Matt DeGuy" }, replace_doc)
    .await?;
println!(
    "Matched documents: {}\nModified documents: {}",
    res.matched_count, res.modified_count
);

Matched documents: 1
Modified documents: 1

被替换的文档包含替换文档的内容和不可变的_id字段：

{
  "_id": ObjectId('4501'),
  "name": "Susan Lee",
  "role": "Lead Consultant",
  "team_members": [ "Jill Gillison" ]
}

完整文件示例：替换文档

此示例替换 sample_restaurants数据库的 restaurants集合中的文档。 replace_one() 方法将 name字段值为 "Landmark Coffee Shop" 的第一个文档替换为新文档。

您可以将 restaurants集合中的文档作为 Document 类型或自定义数据类型的实例访问权限。要指定代表集合数据的数据类型，请对突出显示的行执行以下操作：

要作为BSON文档访问权限集合文档，请将 <T> 类型参数替换为 <Document>，并将 <struct or doc> 占位符替换为 replace_doc。
要将集合文档作为 Restaurant 结构体的实例访问权限，请将 <T> 类型参数替换为 <Restaurant>，并将 <struct or doc> 占位符替换为 replace_struct。 Restaurant 结构体在代码文件的顶部定义。

选择Asynchronous或Synchronous标签页，查看每个运行时的相应代码：

use std::env;
use mongodb::{ bson::doc, Client, Collection };
use serde::{ Deserialize, Serialize };
#[derive(Serialize, Deserialize, Debug)]
struct Restaurant {
    borough: String,
    cuisine: String,
    name: String,
}
#[tokio::main]
async fn main() -> mongodb::error::Result<()> {
    let uri = "<connection string>";
    let client = Client::with_uri_str(uri).await?;
    // Replace <T> with the <Document> or <Restaurant> type parameter
    let my_coll: Collection<T> = client
        .database("sample_restaurants")
        .collection("restaurants");
    let filter = doc! { "name": "Landmark Coffee Shop" };
    let replace_doc = doc! { 
        "borough": "Brooklyn",
        "cuisine": "Café/Coffee/Tea",
        "name": "Harvest Moon Café",
    };
    let replace_struct = Restaurant {
        borough: "Brooklyn".to_string(),
        cuisine: "Café/Coffee/Tea".to_string(),
        name: "Harvest Moon Café".to_string(),
    };
    // Replace <struct or doc> with the replace_struct or replace_doc variable
    let res = my_coll.replace_one(filter, <struct or doc>).await?;
    println!("Replaced documents: {}", res.modified_count);
    Ok(())
}

Replaced documents: 1

use std::env;
use mongodb::{ bson::doc, sync::{ Client, Collection } };
use serde::{ Deserialize, Serialize };
#[derive(Serialize, Deserialize, Debug)]
struct Restaurant {
    borough: String,
    cuisine: String,
    name: String,
}
fn main() -> mongodb::error::Result<()> {
    let uri = "<connection string>";
    let client = Client::with_uri_str(uri)?;
    // Replace <T> with the <Document> or <Restaurant> type parameter
    let my_coll: Collection<T> = client
        .database("sample_restaurants")
        .collection("restaurants");
    let filter = doc! { "name": "Landmark Coffee Shop" };
    let replace_doc = doc! { 
        "borough": "Brooklyn",
        "cuisine": "Café/Coffee/Tea",
        "name": "Harvest Moon Café",
    };
    let replace_struct = Restaurant {
        borough: "Brooklyn".to_string(),
        cuisine: "Café/Coffee/Tea".to_string(),
        name: "Harvest Moon Café".to_string(),
    };
    // Replace <struct or doc> with the replace_struct or replace_doc variable 
    let res = my_coll.replace_one(filter, <struct or doc>).run()?;
    println!("Replaced documents: {}", res.modified_count);
    Ok(())
}

Replaced documents: 1

修改替换行为

您可以通过调用设立ReplaceOptions 结构体字段的选项方法来修改 replace_one() 方法的行为。

注意

设置选项

您可以通过将选项构建器方法直接链接到 replace_one() 方法调用来设立ReplaceOptions 字段。如果使用的是早期版本的驱动程序，则必须通过将选项构建器方法链接到 builder() 方法来构造 ReplaceOptions实例。然后，将选项实例作为参数传递给 replace_one()。

下表描述了ReplaceOptions中可用的选项：

选项	说明
`array_filters`	指定要应用更新的大量元素的筛选器设立。类型： `Vec<Document>`
`bypass_document_validation`	如果为`true` ，则允许驾驶员执行违反文档级验证的写入。要学习；了解有关验证的更多信息，请参阅模式验证指南。类型： `bool` 默认值：`false`
`upsert`	如果为`true` ，则在没有文档与查询过滤匹配的情况下，该操作会插入一个文档。类型： `bool`
`collation`	对结果进行排序时使用的排序规则。要学习；了解有关排序规则的更多信息，请参阅排序规则指南。类型： `Collation` 默认值：`None`
`hint`	用于操作的索引。类型： `Hint` 默认值：`None`
`write_concern`	该操作的写关注（write concern）。如果不设立此选项，该操作将继承为集合的写关注（write concern）。要学习；了解有关写入关注的更多信息，请参阅MongoDB Server手册中的写关注。类型： `WriteConcern`
`let_vars`	参数和值的映射。这些参数可以作为聚合表达式中的变量进行访问。此选项仅在连接到MongoDB Server5.0 及更高版本时可用。类型：`Document`
`comment`	`Bson`与操作绑定的任意值，以通过数据库分析器、`currentOp` 和日志进行跟踪。此选项仅在连接到MongoDB Server4.4 及更高版本时可用。类型：`Bson` 默认值：`None`

以下代码展示了如何通过将upsert()方法链接到replace_one()方法来设立upsert字段：

let res = my_coll
    .replace_one(filter_doc, replace_doc)
    .upsert(true)
    .await?;

替换文档

Overview

注意

_id 字段

替换文档

提示

参数

返回值

示例

替换示例

完整文件示例：替换文档

修改替换行为

注意

设置选项

更多信息

API 文档