/ /

Operaciones de escritura masiva

Overview

En esta guía, puedes aprender a realizar múltiples operaciones de escritura en una sola llamada a la base de datos utilizando operaciones de escritura en bloque.

Piensa en un escenario en el que necesitas insertar un documento en una colección, actualizar varios otros documentos y luego borrar un documento. Si utilizas métodos individuales, cada operación requiere su propia llamada a la base de datos. En su lugar, puedes usar una operación por lotes para reducir el número de llamadas a la base de datos.

Datos de muestra

Los ejemplos de esta guía utilizan la colección restaurants en la base de datos sample_restaurants de los conjuntos de datos de muestra de Atlas. Para acceder a esta colección desde tu aplicación en C++, instancia un mongocxx::client que se conecte a un clúster Atlas y asigna los siguientes valores a tus variables db y collection:

auto db = client["sample_restaurants"];
auto collection = db["restaurants"];

Para aprender cómo crear un clúster gratuito de MongoDB Atlas y cargar los conjuntos de datos de ejemplo, consulta la guía MongoDB Get Started.

Crear una instancia de escritura masiva

Antes de ejecutar una operación de guardar masiva, llama al método create_bulk_write() en una colección. Este método devuelve una instancia de la clase mongocxx::bulk_write que se puede utilizar para guardar instrucciones sobre qué tipos de escrituras masivas realizar.

El siguiente ejemplo llama al método create_bulk_write() en la colección restaurants:

auto bulk = collection.create_bulk_write();

Luego puedes anexar modelos de guardar a tu instancia de mongocxx::bulk_write para definir la operación masiva. Para obtener más información, consulte la siguiente sección Definir las Operaciones de Guardar.

Defina las operaciones de guardado

Para cada operación de escritura que desees realizar, crea una instancia de una de las siguientes clases de modelos:

mongocxx::model::insert_one
mongocxx::model::update_one
mongocxx::model::update_many
mongocxx::model::replace_one
mongocxx::model::delete_one
mongocxx::model::delete_many

A continuación, añade cada modelo de guardar a la instancia mongocxx::bulk_write devuelta por el método create_bulk_write().

Las siguientes secciones muestran cómo crear y utilizar instancias de las clases anteriores del modelo de guardar.

Operaciones de inserción

Para realizar una operación de inserción, crea una instancia de la clase mongocxx::model::insert_one y especifica el documento que deseas insertar. Luego, añade la instancia del modelo a una instancia de la clase mongocxx::bulk_write.

El siguiente ejemplo crea una instancia de mongocxx::model::insert_one y la añade a una instancia de mongocxx::bulk_write llamada bulk:

auto insert_doc = make_document(kvp("name", "Mongo's Deli"),
                                kvp("cuisine", "Sandwiches"),
                                kvp("borough", "Manhattan"),
                                kvp("restaurant_id", "1234"));
mongocxx::model::insert_one insert_op{insert_doc.view()};
bulk.append(insert_op);

Para insertar varios documentos, cree una instancia de mongocxx::model::insert_one para cada documento.

Operaciones de actualizar

Para actualizar un documento, se debe crear una instancia de mongocxx::model::update_one. Este modelo indica al driver que actualice el primer documento que coincida con tu filtro de query. A continuación, añade la instancia del modelo a una instancia de la clase mongocxx::bulk_write.

Pasa los siguientes argumentos al modelo mongocxx::model::update_one:

Documento de filtro de query, que especifica los criterios utilizados para hacer coincidir documentos en la colección.
Actualizar documento, que especifica el tipo de actualización a realizar. Para obtener más información sobre las operaciones de actualización, consulta la guía Operadores de actualización de campo en el Manual del Servidor MongoDB.

El siguiente ejemplo crea una instancia de mongocxx::model::update_one y la añade a una instancia de mongocxx::bulk_write llamada bulk:

auto filter_doc = make_document(kvp("name", "Mongo's Deli"));
auto update_doc = make_document(kvp("$set", make_document(kvp("cuisine", "Sandwiches and Salads"))));
mongocxx::model::update_one update_op{filter_doc.view(), update_doc.view()};
bulk.append(update_op);

Para actualizar varios documentos, crea una instancia de mongocxx::model::update_many e ingresa los mismos argumentos. Este modelo indica al driver que actualice todos los documentos que coincidan con tu filtro de query.

El siguiente ejemplo crea una instancia de mongocxx::model::update_many y la agrega a bulk:

auto filter_doc = make_document(kvp("name", "Mongo's Deli"));
auto update_doc = make_document(kvp("$set", make_document(kvp("cuisine", "Sandwiches and Salads"))));
mongocxx::model::update_many update_op{filter_doc.view(), update_doc.view()};
bulk.append(update_op);

Reemplazar operaciones

Una operación de reemplazo remueve todos los campos y valores de un documento especificado y los reemplaza por otros nuevos. Para realizar una operación de reemplazo, cree una instancia de la clase mongocxx::model::replace_one y pásela un filtro de query junto con los campos y valores que desea almacenar en el documento coincidente. Luego, agrega la instancia del modelo a una instancia de la clase mongocxx::bulk_write.

El siguiente ejemplo crea una instancia de mongocxx::model::replace_one y la añade a una instancia de mongocxx::bulk_write llamada bulk:

auto filter_doc = make_document(kvp("restaurant_id", "1234"));
auto replace_doc = make_document(kvp("name", "Mongo's Deli"),
                                kvp("cuisine", "Sandwiches and Salads"),
                                kvp("borough", "Brooklyn"),
                                kvp("restaurant_id", "5678"));
mongocxx::model::replace_one replace_op{filter_doc.view(), replace_doc.view()};
bulk.append(replace_op);

Para reemplazar varios documentos, debe crear una nueva instancia de mongocxx::model::replace_one para cada documento.

Operaciones de borrar

Para borrar un documento, crea una instancia de la clase mongocxx::model::delete_one y pasa un filtro de query que especifique el documento que deseas borrar. Este modelo indica al driver que borre solo el primer documento que coincida con tu filtro de query. A continuación, añade la instancia del modelo a una instancia de la clase mongocxx::bulk_write.

El siguiente ejemplo crea una instancia de mongocxx::model::delete_one y la añade a una instancia de mongocxx::bulk_write llamada bulk:

auto filter_doc = make_document(kvp("restaurant_id", "5678"));
mongocxx::model::delete_one delete_op{filter_doc.view()};
bulk.append(delete_op);

Para borrar varios documentos, crea una instancia de la clase mongocxx::model::delete_many e ingresa un filtro de query que especifique el documento que quieres borrar. Este modelo instruye al driver a borrar todos los documentos que coincidan con su filtro de query.

El siguiente ejemplo crea una instancia de mongocxx::model::delete_many y la agrega a bulk:

auto filter_doc = make_document(kvp("borough", "Manhattan"));
mongocxx::model::delete_many delete_op{filter_doc.view()};
bulk.append(delete_op);

Ejecutar la operación masiva

Para ejecutar una operación masiva, llama al método execute() en una instancia de la clase mongocxx::bulk_write que contenga tus modelos de escritura. Por defecto, el método execute() ejecuta las operaciones en el orden en que se agregan a la instancia mongocxx::bulk_write.

El siguiente ejemplo realiza las operaciones de inserción, actualización, reemplazo y borrar especificadas en las secciones anteriores de esta guía, añadiendo cada modelo de guardar correspondiente a una instancia de mongocxx::bulk_write y llamando al método execute(). Luego, imprime la cantidad de documentos modificados:

auto bulk = collection.create_bulk_write();
// Specifies documents to insert, update, replace, or delete
auto insert_doc = make_document(kvp("name", "Mongo's Deli"),
                                kvp("cuisine", "Sandwiches"),
                                kvp("borough", "Manhattan"),
                                kvp("restaurant_id", "1234"));
auto update_filter = make_document(kvp("name", "Mongo's Deli"));
auto update_doc = make_document(kvp("$set", make_document(kvp("cuisine", "Sandwiches and Salads"))));
auto replace_filter = make_document(kvp("restaurant_id", "1234"));
auto replace_doc = make_document(kvp("name", "Mongo's Deli"),
                                kvp("cuisine", "Sandwiches and Salads"),
                                kvp("borough", "Brooklyn"),
                                kvp("restaurant_id", "5678"));
auto delete_filter = make_document(kvp("borough", "Manhattan"));
// Creates write models for each write operation using the preceding documents
mongocxx::model::insert_one insert_op{insert_doc.view()};
mongocxx::model::update_many update_op{update_filter.view(), update_doc.view()};
mongocxx::model::replace_one replace_op{replace_filter.view(), replace_doc.view()};
mongocxx::model::delete_many delete_op{delete_filter.view()};
// Appends each write model to the bulk operation
bulk.append(insert_op);
bulk.append(update_op);
bulk.append(replace_op);
bulk.append(delete_op);
// Runs the bulk operation
auto result = bulk.execute();
std::cout << "Modified documents: " << result->modified_count() << std::endl;

Modified documents: 2

Si alguna de las operaciones de escritura falla, el controlador C++ genera un mongocxx::bulk_write_exception y no realiza más operaciones.

Tip

Para obtener más información sobre la función modified_count(), consulta la sección Valor de retorno de esta guía.

Personaliza las operaciones de escritura masiva

Puede modificar el comportamiento del método create_bulk_write() pasando una instancia de la clase mongocxx::options::bulk_write como parámetro. La siguiente tabla describe los campos que puedes establecer en una instancia de mongocxx::options::bulk_write:

Campo	Descripción
`ordered`	Si `true` es, el controlador realiza las operaciones de escritura en el orden especificado. Si se produce un error, no se intentan las operaciones restantes. Si `false` es, el controlador realiza las operaciones en un orden arbitrario e intenta realizarlas todas. El valor predeterminado `true` es.
`bypass_document_validation`	Especifica si la operación omite la validación a nivel de documento. Para obtener más información, consulte Validación de esquema en el manual del servidor MongoDB. El valor predeterminado `false` es.
`write_concern`	Especifica el nivel de confirmación de escritura (write concern) para la operación en lote. Para obtener más información, consulta nivel de confirmación de escritura (write concern) en el manual de MongoDB Server.
`comment`	Anexa un comentario a la operación. Para obtener más información, consulta la guía sobre los campos del comando borrar en el manual del MongoDB Server.
`let`	Especifica un documento con una lista de valores para mejorar la legibilidad de la operación. Los valores deben ser expresiones constantes o cerradas que no hagan referencia a campos de documentos. Para obtener más información, consulta la instrucción let en el manual de MongoDB Server.

El siguiente ejemplo llama al método create_bulk_write() desde el ejemplo Crear una instancia de escritura masiva en esta página, pero establece el campo ordered de una instancia mongocxx::options::bulk_write en false:

mongocxx::options::bulk_write opts;
opts.ordered(false);
auto bulk = collection.create_bulk_write(opts);

Si alguna de las operaciones de guardado en un proceso de guardado masivo desordenado falla, el driver de C++ informa de los errores solo después de intentar todas las operaciones.

Nota

Las operaciones masivas no ordenadas no ofrecen garantías del orden de ejecución. El orden puede diferir de la manera en que los enumeras para optimizar el tiempo de ejecución.

Valor de retorno

El método execute() retorna una instancia de la clase mongocxx::result::bulk_write. La clase mongocxx::result::bulk_write contiene las siguientes funciones miembro:

Función	Descripción
`deleted_count()`	Devuelve el número de documentos borrados, si los hay.
`inserted_count()`	Devuelve el número de documentos insertados, si los hay.
`matched_count()`	Devuelve el número de documentos coincidentes para una actualización, si corresponde.
`modified_count()`	Devuelve el número de documentos modificados, si los hay.
`upserted_count()`	Devuelve el número de documentos actualizados o insertados, si los hay.
`upserted_ids()`	Devuelve un mapa del índice de la operación al `_id` de los documentos upserted, si corresponde.

Información Adicional

Para aprender cómo realizar operaciones de guardar individuales, consulta los siguientes guías:

Documentación de la API

Para aprender más sobre cualquiera de los métodos o tipos analizados en esta guía, consulta la siguiente documentación de API:

Volver

Borrar

GridFS