Overview
En esta guía, puede aprender cómo utilizar el driver .NET/C# para realizar operaciones de escritura masiva. Al utilizar una operación de escritura masiva, puedes realizar múltiples operaciones de guardado en menos llamadas a la base de datos.
Considera una situación que requiere que insertes documentos, actualices documentos y borres documentos para la misma tarea. Si utilizas los métodos de guardado individuales para realizar cada tipo de operación, cada guardado accede a la base de datos por separado. Se puede utilizar una operación de escritura masiva para optimizar el número de llamadas que la aplicación realiza al servidor.
Puedes utilizar el IMongoCollection.BulkWrite() o el método IMongoCollection.BulkWriteAsync() para realizar operaciones de escritura masiva en una sola colección. Cada método toma una lista de WriteModel<TDocument> instancias que describen las operaciones de escritura a realizar.
Datos de muestra
Los ejemplos en esta guía utilizan la colección sample_restaurants.restaurants de la Conjuntos de datos de muestra de Atlas. Para aprender a crear un clúster gratuito de MongoDB Atlas y cargar los conjuntos de datos de muestra, consulte
Tutorial de inicio rápido.
Defina las operaciones de guardado
Para cada operación de guardar que desees realizar, crea una instancia de una de las siguientes clases WriteModel<TDocument>:
DeleteManyModel<TDocument>DeleteOneModel<TDocument>InsertOneModel<TDocument>ReplaceOneModel<TDocument>UpdateManyModel<TDocument>UpdateOneModel<TDocument>
Las siguientes secciones muestran cómo crear y utilizar instancias de las clases anteriores para realizar la operación de escritura correspondiente en una operación de escritura masiva.
Tip
Operaciones de guardado en bloque con POCOs
Los ejemplos en esta guía utilizan el tipo BsonDocument para el tipo TDocument en todas las clases genéricas. También puedes utilizar un Objeto CLR Antiguo Simple (POCO) para estas clases. Para ello, debes definir una clase que represente los documentos en tu colección. La clase debe tener propiedades que coincidan con los campos de tus documentos. Para más información, consulta POCOs.
Operaciones de inserción
Para realizar una operación de inserción, cree una instancia InsertOneModel<TDocument> y especifique el documento que desea insertar.
El siguiente ejemplo crea una instancia de la clase InsertOneModel<BsonDocument>. Esta instancia orienta al driver a insertar un documento en el que el campo "name" es "Mongo's Deli" en la colección restaurants.
var insertOneModel = new InsertOneModel<BsonDocument>( new BsonDocument{ { "name", "Mongo's Deli" }, { "cuisine", "Sandwiches" }, { "borough", "Manhattan" }, { "restaurant_id", "1234" } } );
Para insertar varios documentos, cree una instancia de InsertOneModel<TDocument> para cada documento.
Importante
Error de clave duplicada
Al realizar una operación masiva, el InsertOneModel<TDocument> no puede insertar un documento con un _id ya existente en la colección. En este caso, el controlador lanza un MongoBulkWriteException.
Operaciones de actualizar
Para actualizar un solo documento, cree un instancia de UpdateOneModel<TDocument> y pase los siguientes argumentos:
Filtro de consulta que especifica los criterios utilizados para buscar documentos en su colección. Para obtener más información sobre cómo especificar una consulta, consulte "Operadores de consulta y proyección" en el manual de MongoDB Server.
Documento de actualización que describe la actualización a realizar. Para obtener más información sobre cómo especificar una actualización, consulte "Operadores de actualización" en el manual de MongoDB Server.
Una UpdateOneModel<TDocument> instancia especifica una actualización para el primer documento que coincide con su filtro de consulta.
En el siguiente ejemplo de código, el objeto UpdateOneModel<BsonDocument> representa una operación de actualización en la colección restaurants. La operación coincide con el primer documento en la colección donde el valor del campo name es "Mongo's Deli". Luego actualiza el valor del campo cuisine en el documento coincidente a "Sandwiches and Salads".
var updateOneModel = new UpdateOneModel<BsonDocument>( Builders<BsonDocument>.Filter.Eq("name", "Mongo's Deli"), Builders<BsonDocument>.Update.Set("cuisine", "Sandwiches and Salads") );
Para actualizar varios documentos, cree una instancia de UpdateManyModel<TDocument> y pase los mismos argumentos que para UpdateOneModel<TDocument>. La clase UpdateManyModel<TDocument> especifica actualizaciones para todos los documentos que coincidan con su filtro de query.
En el siguiente ejemplo de código, el objeto UpdateManyModel<BsonDocument> representa una operación de actualización en la colección restaurants. La operación coincide con todos los documentos de la colección donde el valor del campo name es "Mongo's Deli". Luego actualiza el valor del campo cuisine a "Sandwiches and Salads".
var updateManyModel = new UpdateManyModel<BsonDocument>( Builders<BsonDocument>.Filter.Eq("name", "Mongo's Deli"), Builders<BsonDocument>.Update.Set("cuisine", "Sandwiches and Salads") );
Reemplazar operaciones
Una operación de reemplazo remueve todos los campos y valores de un documento especificado y los reemplaza por nuevos campos y valores que usted especifica. Para realizar una operación de reemplazo, crea una instancia de ReplaceOneModel<TDocument> y pasa un filtro de query junto con los campos y valores con los que deseas reemplazar el documento coincidente.
En el siguiente ejemplo, el objeto ReplaceOneModel<BsonDocument> representa una operación de reemplazo en la colección restaurants. La operación coincide con el documento en la colección donde el valor del campo restaurant_id es "1234". Luego remueve todos los campos, excepto _id, de este documento y establece nuevos valores en los campos name, cuisine, borough y restaurant_id.
var replaceOneModel = new ReplaceOneModel<BsonDocument>( Builders<BsonDocument>.Filter.Eq("restaurant_id", "1234"), new BsonDocument{ { "name", "Mongo's Pizza" }, { "cuisine", "Pizza" }, { "borough", "Brooklyn" }, { "restaurant_id", "5678" } } );
Para reemplazar varios documentos, debe crear una instancia de ReplaceOneModel<TDocument> para cada documento.
Operaciones de borrar
Para borrar un documento, crea una instancia de DeleteOneModel<TDocument> y pasa un filtro de query que especifique el documento que deseas borrar. Una instancia DeleteOneModel<TDocument> proporciona instrucciones para eliminar solo el primer documento que coincida con tu filtro de query.
En el siguiente ejemplo de código, el objeto DeleteOneModel<BsonDocument> representa una operación de eliminación en la colección restaurants. La operación busca y elimina el primer documento donde el valor del campo restaurant_id es "5678".
var deleteOneModel = new DeleteOneModel<BsonDocument>( Builders<BsonDocument>.Filter.Eq("restaurant_id", "5678") );
Para borrar varios documentos, crea una instancia de DeleteManyModel<TDocument> y pasa un filtro de query que especifique los documentos que deseas borrar. Una instancia de DeleteManyModel<TDocument> proporciona instrucciones para remover todos los documentos que coincidan con el filtro de query.
En el siguiente ejemplo de código, el objeto DeleteManyModel<BsonDocument> representa una operación de eliminación en la colección restaurants. La operación coincide y elimina todos los documentos donde el valor del campo name es "Mongo's Deli".
var deleteManyModel = new DeleteManyModel<BsonDocument>( Builders<BsonDocument>.Filter.Eq("name", "Mongo's Deli") );
Realizar la Operación Masiva
Después de definir una instancia WriteModel para cada operación que desee realizar, cree una instancia de una clase que implemente la interfaz IEnumerable. Agrega tus objetos de WriteModel a este IEnumerable, luego pasa el IEnumerable al método BulkWrite() o BulkWriteAsync(). Por defecto, estos métodos ejecutan las operaciones en el orden en que están definidos en la lista.
Tip
IEnumerable
Array y List son dos clases comunes que implementan la interfaz IEnumerable.
Selecciona de las siguientes pestañas para ver cómo usar el método sincrónico BulkWrite() y el método asincrónico BulkWriteAsync() para realizar una operación de escritura masiva en la colección restaurants:
var models = new List<WriteModel<BsonDocument>> { new InsertOneModel<BsonDocument>( new BsonDocument{ { "name", "Mongo's Deli" }, { "cuisine", "Sandwiches" }, { "borough", "Manhattan" }, { "restaurant_id", "1234" } } ), new InsertOneModel<BsonDocument>( new BsonDocument{ { "name", "Mongo's Deli" }, { "cuisine", "Sandwiches" }, { "borough", "Brooklyn" }, { "restaurant_id", "5678" } } ), new UpdateManyModel<BsonDocument>( Builders<BsonDocument>.Filter.Eq("name", "Mongo's Deli"), Builders<BsonDocument>.Update.Set("cuisine", "Sandwiches and Salads") ), new DeleteOneModel<BsonDocument>( Builders<BsonDocument>.Filter.Eq("restaurant_id", "1234") ) }; var results = collection.BulkWrite(models); Console.WriteLine(results);
var models = new List<WriteModel<BsonDocument>> { new InsertOneModel<BsonDocument>( new BsonDocument{ { "name", "Mongo's Deli" }, { "cuisine", "Sandwiches" }, { "borough", "Manhattan" }, { "restaurant_id", "1234" } } ), new InsertOneModel<BsonDocument>( new BsonDocument{ { "name", "Mongo's Deli" }, { "cuisine", "Sandwiches" }, { "borough", "Brooklyn" }, { "restaurant_id", "5678" } } ), new UpdateManyModel<BsonDocument>( Builders<BsonDocument>.Filter.Eq("name", "Mongo's Deli"), Builders<BsonDocument>.Update.Set("cuisine", "Sandwiches and Salads") ), new DeleteOneModel<BsonDocument>( Builders<BsonDocument>.Filter.Eq("restaurant_id", "1234") ) }; var results = await collection.BulkWriteAsync(models); Console.WriteLine(results);
Los siguientes ejemplos de código producen la siguiente salida:
MongoDB.Driver.BulkWriteResult1+Acknowledged[MongoDB.Bson.BsonDocument]
Nota
Cuando el controlador ejecuta una operación masiva, utiliza la preocupación de escritura de la colección de destino. El controlador informa todos los errores de preocupación de escritura después de intentar todas las operaciones, independientemente del orden de ejecución.
Personaliza las operaciones de escritura masiva
Al llamar al método BulkWrite() o BulkWriteAsync(), se puede pasar una instancia de la clase BulkWriteOptions. La clase BulkWriteOptions contiene las siguientes propiedades, que representan opciones que se pueden usar para configurar la operación de escritura masiva:
Propiedad | Descripción |
|---|---|
| Specifies whether the operation bypasses document-level validation. For more
information, see Schema
Validation in the MongoDB Server
manual. Defaults to False. |
| A comment to attach to the operation, in the form of a BsonValue. For
more information, see the delete command
fields guide in the
MongoDB Server manual. |
| If True, the driver performs the write operations in the order
provided. If an error occurs, the remaining operations are not
attempted.If False, the driver performs the operations in an
arbitrary order and attempts to perform all operations. If any of the write
operations in an unordered bulk write fail, the driver
reports the errors only after attempting all operations.Defaults to True. |
| A map of parameter names and values, in the form of a BsonDocument. Values
must be constant or closed
expressions that don't reference document fields. For more information,
see the let statement in the
MongoDB Server manual. |
Los siguientes ejemplos de código usan un objeto BulkWriteOptions para realizar una operación de guardado masivo no ordenada:
Valor de retorno
Los métodos BulkWrite() y BulkWriteAsync() devuelven un objeto BulkWriteResult que contiene las siguientes propiedades:
Propiedad | Descripción |
|---|---|
| Indicates whether the server acknowledged the bulk write operation. If the
value of this property is False and you try to access any other property
of the BulkWriteResult object, the driver throws an exception. |
| The number of documents deleted, if any. |
| The number of documents inserted, if any. |
| The number of documents matched for an update, if applicable. |
| The number of documents modified, if any. |
| Indicates whether the modified count is available. |
| A list that contains information about each request that
resulted in an upsert operation. |
| The number of requests in the bulk operation. |
Manejo de excepciones
Si alguna de las operaciones en una operación de escritura masiva falla, el driver .NET/C# lanza un BulkWriteError y no realiza ninguna otra operación.
Un objeto BulkWriteError contiene la propiedad Index que describe el índice de la solicitud que resultó en un error.
Información Adicional
Para aprender cómo realizar operaciones de guardar individuales, consulta los siguientes guías:
Para aprender más sobre cualquiera de los métodos o tipos analizados en esta guía, consulta la siguiente documentación de API: