/ /

Operaciones compuestas

Overview

En esta guía, puedes aprender a usar el controlador de Rust para realizar operaciones compuestas.

Las operaciones compuestas combinan la funcionalidad de las operaciones de lectura y guardar en una acción atómica. Si realizas una operación de lectura y una operación de guardar en secuencia, alguien podría cambiar tu documento objetivo entre esas operaciones, lo que podría conducir a resultados inesperados. Cuando realizas una operación compuesta, MongoDB previene los cambios temporales de datos colocando un bloqueo de escritura en el documento que estás modificando hasta que la operación se complete.

Puede realizar las siguientes operaciones compuestas con el controlador:

Encuentra y elimina un documento
Buscar y actualizar un documento
Buscar y reemplazar un documento

Esta guía incluye las siguientes secciones:

Datos de muestra para ejemplos presenta los datos de muestra que se utilizan en los ejemplos de operaciones combinadas
Encontrar y borrar un documento describe cómo encontrar y borrar un documento en una sola operación
Encontrar y actualizar un documento describe cómo encontrar y actualizar un documento en una sola operación
Buscar y reemplazar un documento describe cómo buscar y reemplazar un documento en una sola operación
Información adicional proporciona enlaces a recursos y documentación de la API para los tipos y métodos mencionados en esta guía

Tip

Para aprender cómo realizar operaciones de lectura y escritura atómicas en más de un documento al mismo tiempo, consulta la guía de Transacciones.

Datos de muestra para ejemplos

Los ejemplos de esta guía utilizan los siguientes documentos de muestra. Cada documento representa a un estudiante y contiene información sobre su edad y la escuela a la que asisten:

{ "name": "Alex Johnson", "age": 8, "school": "Lakeside Elementary" },
{ "name": "Samara Khan", "age": 11, "school": "Rolling Hills Middle School" },
{ "name": "Ben Joseph", "age": 16, "school": "Aurora High School" },
{ "name": "Deanna Porowski", "age": 10, "school": "Lakeside Elementary" }

Encontrar y borrar un Documento

El método find_one_and_delete() encuentra y borra el primer documento que cumple con el filtro de query especificado. Si un documento cumple con los criterios de filtro, el método devuelve un tipo Some. Si no hay documentos coincidentes, devuelve un tipo None.

Nota

Si deseas realizar otras operaciones entre la búsqueda y la eliminación de un documento, puedes llamar al método find_one() seguido del método delete_one().

Modificar el comportamiento de búsqueda y borrar

Opcionalmente, se puede modificar el comportamiento del método find_one_and_delete() pasando una instancia FineOneAndDeleteOptions como parámetro. Para utilizar los valores por defecto para cada configuración, especifica el valor None para el parámetro de opciones.

La siguiente tabla describe las opciones disponibles en FineOneAndDeleteOptions:

Opción	Descripción
`max_time`	El tiempo máximo en milisegundos que la query puede ejecutarse. Tipo: `Duration`
`projection`	La proyección que se utilizará al devolver los resultados. Tipo: `Document` Por defecto: `None`
`sort`	El orden de clasificación que se utilizará al devolver los resultados. Por defecto, el driver devuelve los documentos en su orden natural, o tal como aparecen en la base de datos. Para obtener más información, consulte orden natural en el glosario del manual del servidor. Tipo: `Document` Por defecto: `None`
`write_concern`	El nivel de confirmación de escritura (write concern) para la operación. Si no establece esta opción, la operación hereda el nivel de confirmación de escritura (write concern) establecido para la colección. Para obtener más información sobre el nivel de confirmación de escritura (write concern), consulta Nivel de confirmación de escritura (write concern) en el manual del servidor. Tipo: `WriteConcern`
`collation`	La intercalación que se utilizará al ordenar los resultados. Para obtener más información sobre las intercalaciones, consulte la guía Intercalación. Tipo: `Collation` Por defecto: `None`
`hint`	El índice que se utilizará para la operación. Para obtener más información sobre los índices, consulte Índices en el manual del servidor. Esta opción solo está disponible cuando se conecta a MongoDB Server versiones 4.4 y posteriores. Tipo: `Hint` Por defecto: `None`
`let_vars`	Un mapa de parámetros y valores. Puede acceder a estos parámetros como variables en expresiones de agregación. Esta opción solo está disponible cuando se conecta a las versiones 5.0 y posteriores de MongoDB Server. Tipo: `Document`
`comment`	Un valor `Bson` arbitrario vinculado a la operación para rastrearlo a través del perfilador de base de datos, `currentOp` y los registros. Esta opción solo está disponible cuando se conecta a MongoDB Server versiones 4.4 y posteriores. Tipo: `Bson` Por defecto: `None`

El controlador de Rust implementa el patrón de diseño del Builder para la creación de una instancia de FindOneAndDeleteOptions. Puedes usar el método builder() del tipo para construir una instancia de opciones encadenando funciones de construcción de opciones una a la vez.

El siguiente código ilustra cómo construir una instancia de FindOneAndDeleteOptions y pasarla al método find_one_and_delete():

let opts = FindOneAndDeleteOptions::builder().comment(bson!("hello")).build();
let res = my_coll.find_one_and_delete(filter, opts).await?;

Buscar y borrar ejemplo

El siguiente ejemplo utiliza el método find_one_and_delete() para buscar y borrar el primer documento donde el valor del campo age es menor o igual a 10:

let filter = doc! { "age": doc! { "$lte": 10 } };
let res = my_coll.find_one_and_delete(filter, None).await?;
println!("Deleted document:\n{:?}", res);

Deleted document:
Some(Document({"_id": ObjectId("..."),
"name": String("Deanna Porowski"), "age": Int32(10), "school":
String("Lakeside Elementary")}))

Buscar y actualizar un documento

El método find_one_and_update() encuentra y actualiza el primer documento que coincida con el filtro de query especificado. La operación actualiza el documento según las especificaciones que se brindan en un documento de actualización. Si un documento coincide con los criterios del filtro, el método devuelve un tipo Some. Si ningún documento coincide, devuelve un tipo None.

Nota

Si desea realizar otras operaciones entre encontrar y actualizar un documento, puede llamar al método find_one() seguido del método update_one().

Modificar el comportamiento de búsqueda y actualización

Opcionalmente, se puede modificar el comportamiento del método find_one_and_update() pasando una instancia FindOneAndUpdateOptions como parámetro. Para utilizar los valores por defecto para cada configuración, especifica el valor None para el parámetro de opciones.

La siguiente tabla describe las opciones disponibles en FineOneAndDeleteOptions:

Opción	Descripción
`array_filters`	El conjunto de filtros que especifica los elementos del arreglo a los que se aplica la actualización. Tipo: `Vec<Document>`
`bypass_document_validation`	Si `true`, permite que el driver realice una operación de guardar que infrinja la validación a nivel de documento. Para obtener más información sobre la validación, consulte Validación de esquemas en el manual del servidor. Tipo: `bool` Por defecto: `false`
`max_time`	El tiempo máximo en milisegundos que la query puede ejecutarse. Tipo: `Duration`
`projection`	La proyección que se utilizará al devolver los resultados. Tipo: `Document` Por defecto: `None`
`return_document`	Si `Before`, la operación devuelve el documento antes de la actualización. Si `After`, la operación devuelve el documento actualizado. Tipo: `ReturnDocument` Por defecto: `ReturnDocument::Before`
`sort`	El orden de clasificación que se utilizará al devolver los resultados. Por defecto, el driver devuelve los documentos en su orden natural, o tal como aparecen en la base de datos. Para obtener más información, consulte orden natural en el glosario del manual del servidor. Tipo: `Document` Por defecto: `None`
`upsert`	Si es verdadero, la operación inserta un documento si ningún documento coincide con el filtro de query. Tipo: `bool` Por defecto: `false`
`write_concern`	El nivel de confirmación de escritura (write concern) para la operación. Si no establece esta opción, la operación hereda el nivel de confirmación de escritura (write concern) establecido para la colección. Para obtener más información sobre el nivel de confirmación de escritura (write concern), consulta Nivel de confirmación de escritura (write concern) en el manual del servidor. Tipo: `WriteConcern`
`collation`	La intercalación que se utilizará al ordenar los resultados. Para obtener más información sobre las intercalaciones, consulte la guía Intercalación. Tipo: `Collation` Por defecto: `None`
`hint`	El índice que se utilizará para la operación. Para obtener más información sobre los índices, consulte Índices en el manual del servidor. Esta opción solo está disponible cuando se conecta a MongoDB Server versiones 4.4 y posteriores. Tipo: `Hint` Por defecto: `None`
`let_vars`	Un mapa de parámetros y valores. Puede acceder a estos parámetros como variables en expresiones de agregación. Esta opción solo está disponible cuando se conecta a las versiones 5.0 y posteriores de MongoDB Server. Tipo: `Document`
`comment`	Un valor `Bson` arbitrario vinculado a la operación para rastrearlo a través del perfilador de base de datos, `currentOp` y los registros. Esta opción solo está disponible cuando se conecta a MongoDB Server versiones 4.4 y posteriores. Tipo: `Bson` Por defecto: `None`

El controlador de Rust implementa el patrón de diseño Builder para la creación de una instancia de FindOneAndUpdateOptions . Puedes usar el método builder() del tipo para construir una instancia de opciones encadenando los métodos del generador de opciones uno a uno.

El siguiente código ilustra cómo construir una instancia de FindOneAndUpdateOptions y pasarla al método find_one_and_update():

let opts = FindOneAndUpdateOptions::builder().comment(bson!("hello")).build();
let res = my_coll.find_one_and_update(filter, update, opts).await?;

Encontrar y actualizar ejemplo

Este ejemplo muestra cómo llamar al método find_one_and_update() con los siguientes parámetros:

Un filtro de query que coincide con un documento donde el valor de school es "Aurora High School"
Un documento de actualización que establece el campo school en "Durango High School" y aumenta el campo age en 1
Una instancia de FindOneAndUpdateOptions que devuelve el documento después de la actualización

let filter = doc! { "school": "Aurora High School" };
let update =
    doc! { "$set": doc! { "school": "Durango High School" },
           "$inc": doc! { "age": 1 } };
let opts = FindOneAndUpdateOptions::builder()
    .return_document(Some(ReturnDocument::After))
    .build();
let res = my_coll.find_one_and_update(filter, update, opts).await?;
println!("Updated document:\n{:?}", res);

Updated document:
Some(Document({"_id": ObjectId("..."),
"name": String("Ben Joseph"), "age": Int32(17), "school":
String("Durango High School")}))

Localizar e substituir um documento

El método find_one_and_replace() encuentra y reemplaza el primer documento que coincide con el filtro de query especificado. La operación reemplaza todos los campos del documento excepto el campo _id con los campos y valores que usted proporcione. Si un documento coincide con los criterios del filtro, el método devuelve un tipo Some. Si ningún documento coincide, devuelve un tipo None.

Nota

Si deseas realizar otras operaciones entre encontrar y reemplazar un documento, puedes llamar al método find_one() seguido del método replace_one().

Modificar el comportamiento de Buscar y reemplazar

Opcionalmente, se puede modificar el comportamiento del método find_one_and_replace() pasando una instancia FindOneAndReplaceOptions como parámetro. Para utilizar los valores por defecto para cada configuración, especifica el valor None para el parámetro de opciones.

La siguiente tabla describe las opciones disponibles en FindOneAndReplaceOptions:

Opción	Descripción
`bypass_document_validation`	Si `true`, permite que el driver realice una operación de guardar que infrinja la validación a nivel de documento. Para obtener más información sobre la validación, consulte Validación de esquemas en el manual del servidor. Tipo: `bool` Por defecto: `false`
`max_time`	El tiempo máximo en milisegundos que la query puede ejecutarse. Tipo: `Duration`
`projection`	La proyección que se utilizará al devolver los resultados. Tipo: `Document` Por defecto: `None`
`return_document`	Si `Before`, la operación devuelve el documento antes de la actualización. Si `After`, la operación devuelve el documento actualizado. Tipo: `ReturnDocument` Por defecto: `ReturnDocument::Before`
`sort`	El orden de clasificación que se utilizará al devolver los resultados. Por defecto, el driver devuelve los documentos en su orden natural, o tal como aparecen en la base de datos. Para obtener más información, consulte orden natural en el glosario del manual del servidor. Tipo: `Document` Por defecto: `None`
`upsert`	Si es verdadero, la operación inserta un documento si ningún documento coincide con el filtro de query. Tipo: `bool` Por defecto: `false`
`write_concern`	El nivel de confirmación de escritura (write concern) para la operación. Si no establece esta opción, la operación hereda el nivel de confirmación de escritura (write concern) establecido para la colección. Para obtener más información sobre el nivel de confirmación de escritura (write concern), consulta Nivel de confirmación de escritura (write concern) en el manual del servidor. Tipo: `WriteConcern`
`collation`	La intercalación que se utilizará al ordenar los resultados. Para obtener más información sobre las intercalaciones, consulte la guía Intercalación. Tipo: `Collation` Por defecto: `None`
`hint`	El índice que se utilizará para la operación. Para obtener más información sobre los índices, consulte Índices en el manual del servidor. Esta opción solo está disponible cuando se conecta a MongoDB Server versiones 4.4 y posteriores. Tipo: `Hint` Por defecto: `None`
`let_vars`	Un mapa de parámetros y valores. Puede acceder a estos parámetros como variables en expresiones de agregación. Esta opción solo está disponible cuando se conecta a las versiones 5.0 y posteriores de MongoDB Server. Tipo: `Document`
`comment`	Un valor `Bson` arbitrario vinculado a la operación para rastrearlo a través del perfilador de base de datos, `currentOp` y los registros. Esta opción solo está disponible cuando se conecta a MongoDB Server versiones 4.4 y posteriores. Tipo: `Bson` Por defecto: `None`

El controlador de Rust implementa el patrón de diseño del Builder para la creación de una instancia de FindOneAndReplaceOptions. Puedes usar el método builder() del tipo para construir una instancia de opciones encadenando funciones de construcción de opciones una a la vez.

El siguiente código ilustra cómo construir una instancia de FindOneAndReplaceOptions y pasarla al método find_one_and_replace():

let opts = FindOneAndReplaceOptions::builder().comment(bson!("hello")).build();
let res = my_coll.find_one_and_replace(filter, replacement, opts).await?;

Ejemplo de buscar y reemplazar

Este ejemplo muestra cómo llamar al método find_one_and_replace() con los siguientes parámetros:

Un filtro de consulta que coincide con un documento en el que el valor de name incluye la string "Johnson"
Un documento de reemplazo que describe a un estudiante nuevo
Una instancia de FindOneAndReplaceOptions que devuelve el documento tras el reemplazo y proyecta únicamente los campos name y school en la salida

let filter = doc! { "name": doc! { "$regex": "Johnson" } };
let replacement =
    doc! { "name": "Toby Fletcher", 
           "age": 14,
           "school": "Durango High School" };
let opts = FindOneAndReplaceOptions::builder()
    .return_document(Some(ReturnDocument::After))
    .projection(doc! { "name": 1, "school": 1, "_id": 0 })
    .build();
let res = my_coll.find_one_and_replace(filter, replacement, opts).await?;
println!("Document after replacement:\n{:?}", res);

Document after replacement:
Some(Document({"name": String("Toby Fletcher"), "school":
String("Durango High School")}))

Información Adicional

Para obtener más información sobre las operaciones en esta guía, consulte la siguiente documentación:

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

Operaciones masivas

Serialización