Reemplazar Documentos

El campo _id

Cada documento en una colección de MongoDB tiene un campo _id único e inmutable. Si intenta cambiar el campo _id mediante una operación de reemplazo, el controlador genera una excepción WriteError y no realiza ninguna actualización.

Parámetros

El método replace_one() acepta los siguientes parámetros:

• Filtro de consulta para que coincida con el documento que se va a reemplazar

• Documentos de reemplazo que contienen los campos y valores que reemplazarán a un documento existente.

Los documentos de reemplazo utilizan el siguiente formato:

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

Valor de retorno

El método replace_one() devuelve un tipo UpdateResult si la operación se realiza correctamente. El tipo UpdateResult contiene las siguientes propiedades que describen la operación:

Si varios documentos coinciden con el filtro de query que pasas a replace_one(), el método selecciona y reemplaza el primer documento que coincida. Si ningún documento coincide con el filtro de query, la operación de reemplazo no realiza ningún cambio.

Ejemplo de reemplazo

El siguiente documento describe a un empleado de una empresa:

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

Este ejemplo utiliza el método replace_one() para reemplazar el documento anterior con uno que tenga los siguientes campos:

• Un valor name de "Susan Lee"

• Un valor role de "Lead Consultant"

• Un 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

El documento reemplazado contiene el contenido del documento de reemplazo y el campo inmutable _id:

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

Ejemplo de archivo completo: Reemplazar un documento

Este ejemplo reemplaza un documento de la colección restaurants de la base de datos sample_restaurants. El método replace_one() reemplaza el primer documento cuyo valor del campo name sea "Landmark Coffee Shop" por un nuevo documento.

Puede acceder a los documentos de la colección restaurants como instancias del tipo Document o como un tipo de dato personalizado. Para especificar qué tipo de dato representa los datos de la colección, realice las siguientes acciones en las líneas resaltadas:

• Para acceder a los documentos de la colección como documentos BSON, sustituye el parámetro <T> tipo por <Document> y el marcador de posición <struct or doc> por replace_doc.

• Para acceder a los documentos de la colección como instancias de la estructura Restaurant, reemplaza el parámetro de tipo <T> por <Restaurant> y el marcador de posición <struct or doc> por replace_struct. La estructura Restaurant se define en la parte superior del archivo de código.

Selecciona el Asynchronous o la pestaña Synchronous para ver el código correspondiente para cada entorno de ejecución:

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

Documentación de la API

Para obtener más información sobre los métodos y tipos mencionados en esta guía, vea la siguiente documentación de la API:

• replace_one()

• UpdateResult

• ReplaceOptions

• WriteError