Modificar documentos

Actualizar patrón de documento

En MongoDB, todos los métodos para cambiar documentos siguen el mismo patrón:

Estos métodos toman los siguientes parámetros:

• Un filtro de consulta para hacer coincidir uno o más documentos para cambiar

• Un documento de actualización que especifica los cambios de campo y valor

El controlador Rust proporciona los siguientes métodos para cambiar documentos:

• update_one()

• update_many()

• replace_one()

Puede recuperar y modificar datos en una sola acción mediante operaciones compuestas. Para obtener más información, consulte la guía sobre Operaciones compuestas.

El campo _id

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

Parámetros

Cada método utiliza un filtro de consulta y un documento de actualización que incluye al menos un operador de actualización. Este operador especifica el tipo de actualización que se realizará e incluye los campos y valores que describen el cambio. Los documentos de actualización utilizan el siguiente formato:

doc! { "<update operator>": doc! { "<field>": <value> } }

Para especificar varias actualizaciones en un documento de actualización, utilice el siguiente formato:

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

Consulte el manual del servidor MongoDB para obtener una lista completa de operadores de actualización y descripciones.

Valor de retorno

Los métodos update_one() y update_many() devuelven 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 se pasa a UpdateOne(), el método selecciona y actualiza el primer documento que coincida. Si ningún documento corresponde al filtro de query, la operación de actualización no realiza ningún cambio.

Ejemplo de actualización

Los siguientes documentos describen a los empleados de una empresa:

{
  "_id": ObjectId('4337'),
  "name": "Shelley Olson",
  "department": "Marketing",
  "role": "Director",
  "bonus": 3000
},
{
  "_id": ObjectId('4902'),
  "name": "Remi Ibrahim",
  "department": "Marketing",
  "role": "Consultant",
  "bonus": 1800
}

Este ejemplo realiza una operación de actualización con el método update_many(). El método update_many() acepta los siguientes parámetros:

• Un filtro de consulta para encontrar documentos donde el valor del campo department es "Marketing"

• Un documento de actualización que contiene las siguientes actualizaciones:

  • Un operador $set para cambiar el valor de department a "Business Operations" y de role a "Analytics Specialist"

  • Un operador $inc para aumentar el valor de bonus en 500

let update_doc = doc! {
        "$set": doc! { "department": "Business Operations",
                      "role": "Analytics Specialist" },
        "$inc": doc! { "bonus": 500 }
};
let res = my_coll
    .update_many(doc! { "department": "Marketing" }, update_doc)
    .await?;
println!("Modified documents: {}", res.modified_count);

Modified documents: 2

Los siguientes documentos reflejan los cambios resultantes de la operación de actualización anterior:

{
  "_id": ObjectId('4337'),
  "name": "Shelley Olson",
  "department": "Business Operations",
  "role": "Analytics Specialist",
  "bonus": 3500
},
{
  "_id": ObjectId('4902'),
  "name": "Remi Ibrahim",
  "department": "Business Operations",
  "role": "Analytics Specialist",
  "bonus": 2300
}

Ejemplo de actualización por ObjectId

El siguiente documento describe a un empleado de una empresa:

{
  "_id": ObjectId('4274'),
  "name": "Jill Millerton",
  "department": "Marketing",
  "role": "Consultant"
}

Este ejemplo consulta el documento anterior especificando un filtro de consulta que coincide con el valor único _id del documento. A continuación, el código realiza una operación de actualización con el método update_one(). El método update_one() acepta los siguientes parámetros:

• Filtro de consulta que coincide con un documento en el que el valor del campo _id es ObjectId('4274')

• Actualizar el documento que crea instrucciones para establecer el valor de name a "Jill Gillison"

let id = ObjectId::from_str("4274").expect("Could not convert to ObjectId");
let filter_doc = doc! { "_id": id };
let update_doc = doc! {
        "$set": doc! { "name": "Jill Gillison" }
};
let res = my_coll
    .update_one(filter_doc, update_doc)
    .await?;
println!("Modified documents: {}", res.modified_count);

Modified documents: 1

El siguiente documento refleja los cambios resultantes de la operación de actualización anterior:

{
  "_id": ObjectId('4274'),
  "name": "Jill Gillison",
  "department": "Marketing",
  "role": "Consultant"
}

Parámetros

El replace_one() método utiliza un filtro de consulta y un documento de reemplazo, que contiene los campos y valores que reemplazarán a un documento existente. Los documentos de reemplazo utilizan el siguiente formato:

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

Return Values

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 consulta que se pasa a replace_one(), el método selecciona y reemplaza el primer documento coincidente. Si ningún documento coincide con el filtro de consulta, la operación de reemplazo no realiza cambios.

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" ]
}

Documentación de la API

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

• update_one()

• update_many()

• UpdateResult

• UpdateOptions

• reemplazar_uno()

• Reemplazar opciones

• Error de escritura