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 query para hacer coincidir uno o más documentos para cambiar

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

• (Opcional) Un tipo de opciones para modificar el comportamiento por defecto del método

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

• update_one()

• update_many()

• replace_one()

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

El campo _id

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

Parámetros

Cada método toma un filtro de query y un documento de actualización que incluye al menos un operador de actualización. El operador de actualización especifica el tipo de actualización que se debe realizar e incluye los campos y valores que describen el cambio. Actualiza los documentos utilizando el siguiente formato:

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

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

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

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

Las operaciones de actualización también toman un parámetro UpdateOptions. Para aprender más sobre cómo modificar el comportamiento de los métodos de actualización, consulte la sección Modifique el comportamiento de actualización y reemplazo de esta guía.

Valor de retorno

Los métodos update_one() y update_many() devuelven un tipo UpdateResult si la operación es exitosa. 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.

Actualizar ejemplo

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() toma los siguientes parámetros:

• Un filtro de query para hacer coincidir documentos donde el valor del campo department sea "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, None)
    .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
}

actualizar por ObjectId ejemplo

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 precedente mediante la especificación de un filtro de query para coincidir con el valor único _id del documento. Luego, el código realiza una operación de actualización con el método update_one(). El método update_one() toma los siguientes parámetros:

• Filtro de query 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, None)
    .await?;
println!("Modified documents: {}", res.modified_count);

Modified documents: 1

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

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

Parámetros

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

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

Las operaciones de reemplazo también toman un parámetro UpdateOptions. Para aprender a modificar el comportamiento del método replace_one(), consulta la sección Modificar el comportamiento de actualización y reemplazo de esta guía.

Return Values

El método replace_one devuelve un tipo UpdateResult si la operación es exitosa. 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, None)
    .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, vea la siguiente documentación de la API:

• update_one()

• update_many()

• UpdateResult

• UpdateOptions

• replace_one()

• ReplaceOptions

• WriteError