/ /

/ /

Librerías de clientes

Rust

Driver Rust

Operaciones CRUD

Update Documents

Overview

En esta guía, puedes aprender cómo usar el controlador Rust para actualizar documentos en una colección de MongoDB usando el update_one() y update_many() métodos.

Las operaciones de actualización modifican los campos que se especifican, dejando los demás campos y valores sin cambios.

Actualizar patrón de documento

En MongoDB, los métodos de actualización siguen el mismo patrón:

Estos métodos toman los siguientes parámetros:

Filtro de query para que coincida con uno o más documentos que se van a actualizar
Actualizar documento que especifica los cambios de campo y valor

Tip

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 a través de una operación de actualización, el controlador emitirá un WriteError y no realizará ninguna actualización.

Operaciones de actualizar

Puedes realizar operaciones para actualizar usando los siguientes métodos:

update_one()que actualiza el primer documento que coincide con los criterios de búsqueda.
update_many(), que actualiza todos los documentos que coinciden con los criterios de búsqueda

También se pueden encadenar métodos del generador de opciones a estos métodos de operación de actualización. Para aprender sobre la modificación del comportamiento de los métodos de actualización, consulta el Modificar comportamiento de actualización sección de esta guía.

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>},
    ...
}

Consulta el manual de MongoDB Server para obtener una lista completa de operador de actualizar y sus descripción.

Nota

Pipelines de agregación en operaciones de actualización

Puedes utilizar pipelines de agregación para realizar operaciones. Para obtener más información sobre las etapas de agregación que MongoDB admite, consulta el tutorial sobre actualizaciones con pipelines de agregación en el manual de MongoDB Server.

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:

Propiedad	Descripción
`matched_count`	El número de documentos que coinciden con el filtro
`modified_count`	El número de documentos modificados por la operación
`upserted_id`	El `_id` del documento actualizado o vacío si no existe ninguno

Si varios documentos coinciden con el filtro de query que se pasa a update_one(), 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.

Ejemplos

Esta sección proporciona referencias rápidas y ejemplos completos de archivos de los métodos update_one() y update_many().

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 utilizando el método update_many(). El método update_many() toma los siguientes parámetros:

filtro de query para hacer coincidir documentos donde el valor del campo department es "Marketing"
Actualiza el documento 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
}

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)
    .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"
}

Tip

Para conocer más sobre el campo _id, consulta la sección _id Field en esta página o la documentación del método ObjectId() en el manual del MongoDB Server.

Ejemplo de archivo completo: Actualizar un documento

Este ejemplo actualiza un documento en la colección restaurants de la base de datos sample_restaurants. El método update_one() agrega el campo price al primer documento en el que el valor del campo name es "Spice Market".

Se puede acceder a los documentos en la colección restaurants como instancias del tipo Document o de un tipo de datos personalizado. Para especificar el tipo de dato que representa la colección de datos, reemplaza el parámetro de tipo <T> en la línea resaltada con uno de los siguientes valores:

<Document>: Accede a documentos de la colección como documentos BSON
<Restaurant>: Accede a documentos de la colección como instancias de la estructura Restaurant, definida en la parte superior del 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::{ Document, doc },
    Client,
    Collection
};
use serde::{ Deserialize, Serialize };
#[derive(Serialize, Deserialize, Debug)]
struct Restaurant {
    name: String,
    price: 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": "Spice Market" };
    let update = doc! { "$set": doc! {"price": "$$$"} };
    let res = my_coll.update_one(filter, update).await?;
    println!("Updated documents: {}", res.modified_count);
    Ok(())
}

Updated documents: 1

use std::env;
use mongodb::{
    bson::{ Document, doc },
    sync::{ Client, Collection }
};
use serde::{ Deserialize, Serialize };
#[derive(Serialize, Deserialize, Debug)]
struct Restaurant {
    name: String,
    price: 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": "Spice Market" };
    let update = doc! { "$set": doc! {"price": "$$$"} };
    let res = my_coll.update_one(filter, update).run()?;
    println!("Updated documents: {}", res.modified_count);
    Ok(())
}

Updated documents: 1

Ejemplo de archivo completo: actualiza varios documentos

Este ejemplo actualiza un documento en la colección restaurants de la base de datos sample_restaurants. El método update_many() agrega el campo near_me a los documentos en los que el valor del campo address.street es "Sullivan Street" y el campo borough es "Manhattan".

<Document>: Accede a los documentos de la colección como documentos BSON.
<Restaurant>: Accede a documentos de la colección como instancias de la estructura Restaurant, definida en la parte superior del código

Selecciona la pestaña Asynchronous o Synchronous para ver el código correspondiente para cada runtime:

use std::env;
use mongodb::{ bson::doc, Client, Collection };
use bson::Document;
use serde::{ Deserialize, Serialize };
#[derive(Debug, Serialize, Deserialize)]
struct Address {
    street: String,
    city: String,
}
#[derive(Serialize, Deserialize, Debug)]
struct Restaurant {
    name: String,
    borough: String,
    address: Address,
}
#[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! { 
            "address.street": "Sullivan Street", 
            "borough": "Manhattan" 
        };
    let update = doc! { "$set": doc! { "near_me": true } };
    let res = my_coll.update_many(filter, update).await?;
    println!("Updated documents: {}", res.modified_count);
    Ok(())
}

// Your values might differ
Updated documents: 22

use std::env;
use mongodb::{
    bson::{ Document, doc },
    sync::{ Client, Collection } 
};
use serde::{ Deserialize, Serialize };
#[derive(Debug, Serialize, Deserialize)]
struct Address {
    street: String,
    city: String,
}
#[derive(Serialize, Deserialize, Debug)]
struct Restaurant {
    name: String,
    borough: String,
    address: Address,
}
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! { 
        "address.street": "Sullivan Street", 
        "borough": "Manhattan" 
    };
    let update = doc! { "$set": doc! { "near_me": true } };
    let res = my_coll.update_many(filter, update).run()?;
    println!("Updated documents: {}", res.modified_count);
    Ok(())
}

// Your values might differ
Updated documents: 22

Modificar comportamiento de actualización

Puedes modificar el comportamiento de los métodos update_one() y update_many() llamando a métodos de opciones que establecen los campos struct UpdateOptions.

Nota

Opciones de configuración

Puede establecer los campos de UpdateOptions encadenando métodos de desarrolladores de opciones directamente a la llamada del método de actualización. Si estás usando una versión anterior del controlador, debes construir una instancia de UpdateOptions encadenando métodos del constructor de opciones al método builder(). Luego, pasa tu instancia de opciones como parámetro a update_one() o update_many().

La siguiente tabla describe las opciones disponibles en UpdateOptions:

Opción	Descripción
`array_filters`	The set of filters specifying the array elements to which the update applies. Type: `Vec<Document>`
`bypass_document_validation`	If `true`, allows the driver to perform a write that violates document-level validation. To learn more about validation, see the guide on Schema Validation. Type: `bool` Default: `false`
`upsert`	If `true`, the operation inserts a document if no documents match the query filter. Type: `bool`
`collation`	The collation to use when sorting results. To learn more about collations, see the Collations guide. Type: `Collation` Default: `None`
`hint`	The index to use for the operation. Type: `Hint` Default: `None`
`write_concern`	The write concern for the operation. If you don't set this option, the operation inherits the write concern set for the collection. To learn more about write concerns, see Write Concern in the MongoDB Server manual. Type: `WriteConcern`
`let_vars`	A map of parameters and values. These parameters can be accessed as variables in aggregation expressions. This option is available only when connecting to MongoDB Server versions 5.0 and later. Type: `Document`
`comment`	An arbitrary `Bson` value tied to the operation to trace it through the database profiler, `currentOp`, and logs. This option is available only when connecting to MongoDB Server versions 4.4 and later. Type: `Bson` Default: `None`

El siguiente código muestra cómo establecer el campo upsert mediante el encadenamiento del método upsert() al método update_one():

let res = my_coll
    .update_one(filter_doc, update_doc)
    .upsert(true)
    .await?;

Información Adicional

Para más información sobre los conceptos de esta guía, consulta la siguiente documentación:

Para conocer más sobre los operadores de actualización, consulta Operadores de actualización en el manual de MongoDB Server.

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:

Volver

Query geoespacial

Reemplazar Documentos