Substituir documentos

O campo _id

Cada documento em uma coleção MongoDB tem um campo _id exclusivo e imutável. Se você tentar alterar o campo _id por meio de uma operação de substituição, o driver gerará um WriteError e não executará atualizações.

Parâmetros

O método replace_one() utiliza os seguintes parâmetros:

• Filtro de consulta para corresponder ao documento a ser substituído

• Documentos de substituição que contêm os campos e valores que substituirão um documento existente

Os documentos de substituição usam o seguinte formato:

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

Valor de retorno

O método replace_one() retorna um tipo UpdateResult se a operação for bem-sucedida. O tipo UpdateResult contém as seguintes propriedades que descrevem a operação:

Se vários documentos corresponderem ao filtro de query que você passa para replace_one(), o método selecionará e substituirá o primeiro documento correspondente. Se nenhum documento corresponder ao filtro de query, a operação de substituição não fará alterações.

Exemplo de substituição

O seguinte documento descreve um funcionário de uma empresa:

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

Este exemplo utiliza o método replace_one() para substituir o documento anterior por um que tenha os seguintes campos:

• Um valor name de "Susan Lee"

• Um valor role de "Lead Consultant"

• Um valor team_members de [ "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

O documento substituído contém o conteúdo do documento de substituição e o campo _id imutável:

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

Exemplo de arquivo completo: substituir um documento

Este exemplo substitui um documento na coleção restaurants do banco de dados sample_restaurants. O método replace_one() substitui o primeiro documento no qual o valor do campo name é "Landmark Coffee Shop" por um novo documento.

Você pode acessar os documentos na coleção restaurants como instâncias do tipo Document ou um tipo de dados personalizado. Para especificar qual tipo de dados representa os dados da coleção, execute as seguintes ações nas linhas realçadas:

• Para acessar documentos de coleção como documentos BSON, substitua o parâmetro de tipo <T> por <Document> e o espaço reservado <struct or doc> por replace_doc.

• Para acessar documentos de coleção como instâncias da estrutura Restaurant, substitua o parâmetro de tipo <T> por <Restaurant> e o espaço reservado <struct or doc> por replace_struct. A estrutura Restaurant é definida no topo do arquivo de código.

Selecione a aba Asynchronous ou Synchronous para ver o código correspondente para cada tempo de execução:

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

Documentação da API

Para saber mais sobre os métodos e tipos mencionados neste guia, consulte a documentação da API abaixo:

• replace_one()

• UpdateResult

• ReplaceOptions

• WriteError