/ /

Fundamentals

Guardar

Docs Home

Librerías de clientes

Driver C#/.NET

Fundamentals

Guardar

Operaciones de escritura masiva

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 método IMongoCollection.BulkWrite() o IMongoCollection.BulkWriteAsync() para realizar operaciones de guardado en bloque en una sola colección. Cada método toma una lista de instancias de WriteModel<TDocument> que describen las operaciones de guardado que se deben realizar.

Datos de muestra

Los ejemplos en esta guía utilizan la colección sample_restaurants.restaurants de los 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, consulta el 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 usar instancias de las clases anteriores para realizar la correspondiente operación de guardar en una operación de guardar por lotes.

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 de 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 que ya exista en la colección. En esta situación, el driver lanza un MongoBulkWriteException.

Operaciones de actualizar

Para actualizar un solo documento, cree un instancia de UpdateOneModel<TDocument> y pase los siguientes argumentos:

Filtro de query que especifica los criterios utilizados para seleccionar documentos en tu colección. Para obtener más información sobre cómo especificar una query, consulta Operadores de query y proyección en el manual del MongoDB Server.
Actualizar el documento que describe la actualización que se debe realizar. Para obtener más información sobre cómo especificar una actualización, consulta Operadores de actualización en el manual del MongoDB Server.

Una instancia de UpdateOneModel<TDocument> especifica una actualización para el primer documento que coincida con el filtro de query.

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 driver ejecuta una operación masiva, utiliza el nivel de confirmación de escritura (write concern) de la colección de destino. El driver reporta todos los errores de nivel de confirmación de escritura (write concern) después de intentar todas las operaciones, independientemente del orden de ejecución.

Personaliza las operaciones de escritura masiva

Cuando llamas al método BulkWrite() o BulkWriteAsync(), puedes pasar una instancia de la clase BulkWriteOptions. La clase BulkWriteOptions contiene las siguientes propiedades, que representan opciones que puedes usar para configurar la operación de escritura masiva:

Propiedad	Descripción
`BypassDocumentValidation`	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 de MongoDB Server. por defecto en `False`.
`Comment`	Un comentario para adjuntar a la operación, en forma de `BsonValue`. Para obtener más información, consulte la guía borrar campos de comando en el manual de MongoDB Server.
`IsOrdered`	Si `True`, el driver realiza las operaciones de guardado en el orden proporcionado. Si se produce un error, no se intentarán las operaciones restantes. Si `False`, el driver realiza las operaciones en un orden arbitrario e intenta realizar todas las operaciones. Si alguna de las operaciones de guardado en una escritura masiva desordenada falla, el driver informa de los errores solo después de intentar todas las operaciones. Se establece por defecto en `True`.
`Let`	Un mapa de nombres y valores de parámetros, en forma de `BsonDocument`. Los valores deben ser constantes o expresiones cerradas que no hagan referencia a campos de documentos. Para obtener más información, consulta la instrucción let en el manual del MongoDB Server.

Los siguientes ejemplos de código usan un objeto BulkWriteOptions para realizar una operación de guardado masivo no ordenada:

var models = new List<WriteModel<BsonDocument>>
{
new DeleteOneModel<BsonDocument>(
    Builders<BsonDocument>.Filter.Eq("restaurant_id", "5678")
)
};
var options = new BulkWriteOptions
{
    IsOrdered = false,
};
collection.BulkWrite(models, options);

var models = new List<WriteModel<BsonDocument>>
{
new DeleteOneModel<BsonDocument>(
    Builders<BsonDocument>.Filter.Eq("restaurant_id", "5678")
)
};
var options = new BulkWriteOptions
{
    IsOrdered = false,
};
await collection.BulkWriteAsync(models, options);

Valor de retorno

Los métodos BulkWrite() y BulkWriteAsync() devuelven un objeto BulkWriteResult que contiene las siguientes propiedades:

Propiedad	Descripción
`IsAcknowledged`	Indica si el servidor reconoció la operación de guardado masivo. Si el valor de esta propiedad es `False` e intenta acceder a cualquier otra propiedad del objeto `BulkWriteResult`, el driver arroja una excepción.
`DeletedCount`	El número de documentos borrados, si los hay.
`InsertedCount`	El número de documentos insertados, si los hay.
`MatchedCount`	La cantidad de documentos coincidentes para una actualización, si corresponde.
`ModifiedCount`	El número de documentos modificados, si corresponde.
`IsModifiedCountAvailable`	Indica si el recuento modificado está disponible.
`Upserts`	Una lista que contiene información sobre cada solicitud que resultó en una operación de inserción.
`RequestCount`	El número de solicitudes en la operación masiva.

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:

Volver

Borrar

Lea