/ /

Escrever

Página inicial do Docs

/ /

Fundamentals

Escrever

Página inicial do Docs

Bibliotecas do cliente

Driver C#/ .NET

Fundamentals

Escrever

Operações de gravação em massa

Visão geral

Neste guia, você pode aprender como usar o Driver .NET/C# para executar operações de gravação em massa. Ao usar uma operação de gravação em massa, você pode executar várias operações de gravação em menos chamadas para o banco de dados.

Considere uma situação que exige que você insira documentos, atualize documentos e exclua documentos para a mesma tarefa. Se você usar os métodos de gravação individuais para executar cada tipo de operação, cada gravação acessará o banco de dados de dados separadamente. Você pode usar uma operação de gravação em massa para otimizar o número de chamadas que seu aplicação faz para o servidor.

Você pode usar o método IMongoCollection.BulkWrite() ou IMongoCollection.BulkWriteAsync() para realizar operações de escrita em massa em uma única collection. Cada método recebe uma lista de instâncias WriteModel<TDocument> que descrevem as operações de gravação a serem executadas.

Dados de amostra

Os exemplos neste guia usam a sample_restaurants.restaurants collection dos conjuntos de dados de amostra do Atlas . Para saber como criar um cluster MongoDB Atlas gratuito e carregar os conjuntos de dados de amostra, consulte o tutorialde início rápido.

Definir as operações de gravação

Para cada operação de gravação que você deseja executar, crie uma instância de uma das seguintes classes da WriteModel<TDocument>:

DeleteManyModel<TDocument>
DeleteOneModel<TDocument>
InsertOneModel<TDocument>
ReplaceOneModel<TDocument>
UpdateManyModel<TDocument>
UpdateOneModel<TDocument>

As seções a seguir mostram como criar e usar instâncias das classes anteriores para executar a operação de gravação correspondente em uma operação de gravação em massa.

Dica

Operações de gravação em massa com POCOs

Os exemplos neste guia usam o tipo BsonDocument para o tipo TDocument em todas as classes genéricas. Você também pode usar um objeto antigo e simples de CLR (POCO) para essas classes. Para fazer isso, você deve definir uma classe que represente os documentos em sua coleção. A classe deve ter propriedades que correspondam aos campos em seus documentos. Para obter mais informações, consulte POCOs.

Inserir operações

Para executar uma operação de inserção, crie uma instância do InsertOneModel<TDocument> e especifique o documento que você deseja inserir.

O exemplo seguinte cria uma instância da classe InsertOneModel<BsonDocument>. Essa instância direciona o driver a inserir um documento no qual o campo "name" é "Mongo's Deli" na coleção restaurants.

var insertOneModel = new InsertOneModel<BsonDocument>(
    new BsonDocument{
        { "name", "Mongo's Deli" },
        { "cuisine", "Sandwiches" },
        { "borough", "Manhattan" },
        { "restaurant_id", "1234" }
    }
);

Para inserir vários documentos, crie uma instância de InsertOneModel<TDocument> para cada documento.

Importante

Erro de chave duplicada

Ao executar uma operação em massa, o InsertOneModel<TDocument> não pode inserir um documento com um _id que já existe na coleção. Nessa situação, o driver lança um MongoBulkWriteException.

Atualizar operações

Para atualizar um único documento, crie uma instância de UpdateOneModel<TDocument> e passe os seguintes argumentos:

Filtro de query que especifica os critérios usados para corresponder aos documentos em sua coleção. Para saber mais sobre como especificar uma query, consulte Operadores de query e projeção no manual do MongoDB Server.
documento de atualização que descreve a atualização a ser executada. Para saber mais sobre como especificar uma atualização, consulte Operadores de atualização no manual do MongoDB Server.

Uma instância UpdateOneModel<TDocument> especifica uma atualização para o primeiro documento que corresponde ao seu filtro de query.

No seguinte exemplo de código, o objeto UpdateOneModel<BsonDocument> representa uma operação de atualização na coleção restaurants. A operação corresponde ao primeiro documento na collection em que o valor do campo name é "Mongo's Deli". Em seguida, ele atualiza o valor do campo cuisine no documento correspondente para "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 atualizar vários documentos, crie uma instância de UpdateManyModel<TDocument> e passe os mesmos argumentos de UpdateOneModel<TDocument>. A classe UpdateManyModel<TDocument> especifica atualizações para todos os documentos que correspondem ao seu filtro de query.

No seguinte exemplo de código, o objeto UpdateManyModel<BsonDocument> representa uma operação de atualização na coleção restaurants. A operação corresponde a todos os documentos na coleção onde o valor do campo name é "Mongo's Deli". Em seguida, ele atualiza o valor do campo cuisine para "Sandwiches and Salads".

var updateManyModel = new UpdateManyModel<BsonDocument>(
    Builders<BsonDocument>.Filter.Eq("name", "Mongo's Deli"),
    Builders<BsonDocument>.Update.Set("cuisine", "Sandwiches and Salads")
);

Operações de substituição

Uma operação de substituição remove todos os campos e valores de um documento especificado e os substitui por novos campos e valores especificados por você. Para executar uma operação de substituição, crie uma instância de ReplaceOneModel<TDocument> e passe um filtro de query e os campos e valores pelos quais você deseja substituir o documento correspondente.

No exemplo a seguir, o objeto ReplaceOneModel<BsonDocument> representa uma operação de substituição na coleção restaurants. A operação corresponde ao documento na coleção onde o valor do campo restaurant_id é "1234". Em seguida, ele remove todos os campos exceto _id deste documento e define novos valores nos campos name, cuisine, borough e 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 substituir vários documentos, você deve criar uma instância de ReplaceOneModel<TDocument> para cada documento.

Excluir operações

Para excluir um documento, crie uma instância de DeleteOneModel<TDocument> e passe um filtro de query especificando o documento que deseja excluir. Uma instância do DeleteOneModel<TDocument> fornece instruções para excluir somente o primeiro documento que corresponde ao seu filtro de query.

No seguinte exemplo de código, o objeto DeleteOneModel<BsonDocument> representa uma operação de exclusão na coleção restaurants. A operação corresponde e exclui o primeiro documento onde o valor do campo restaurant_id é "5678".

var deleteOneModel = new DeleteOneModel<BsonDocument>(
    Builders<BsonDocument>.Filter.Eq("restaurant_id", "5678")
);

Para excluir vários documentos, crie uma instância de DeleteManyModel<TDocument> e passe um filtro de query especificando os documentos que deseja excluir. Uma instância de DeleteManyModel<TDocument> fornece instruções para remover todos os documentos que correspondem ao seu filtro de query.

No seguinte exemplo de código, o objeto DeleteManyModel<BsonDocument> representa uma operação de exclusão na coleção restaurants. A operação corresponde e exclui todos os documentos onde o valor do campo name é "Mongo's Deli".

var deleteManyModel = new DeleteManyModel<BsonDocument>(
    Builders<BsonDocument>.Filter.Eq("name", "Mongo's Deli")
);

Executar a operação em massa

Após definir uma instância WriteModel para cada operação que deseja executar, crie uma instância de uma classe que implemente a interface IEnumerable. Adicione seus objetos WriteModel a este IEnumerable e, em seguida, passe o IEnumerable para o método BulkWrite() ou BulkWriteAsync(). Por padrão, esses métodos executam as operações na ordem em que são definidos na lista.

Dica

IEnumerable

Array e List são duas classes comuns que implementam a interface do IEnumerable.

Selecione a partir das seguintes guias para visualizar como utilizar o método BulkWrite() síncrono e o método BulkWriteAsync() assíncrono para executar uma operação de gravação em massa na coleção 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);

Os exemplos de código anteriores produzem a seguinte saída:

MongoDB.Driver.BulkWriteResult1+Acknowledged[MongoDB.Bson.BsonDocument]

Observação

Quando o driver executa uma operação em massa, ele usa a preocupação de gravação da collection de destino. O driver relata todos os erros de preocupação de gravação depois de tentar todas as operações, independentemente da ordem de execução.

Personalizar operações de gravação em massa

Quando você chama o método BulkWrite() ou BulkWriteAsync(), você pode passar uma instância da classe BulkWriteOptions. A classe BulkWriteOptions contém as seguintes propriedades, que representam opções que você pode utilizar para configurar a operação de escrita em massa:

Propriedade	Descrição
`BypassDocumentValidation`	Specifies whether the operation bypasses document-level validation. For more information, see Schema Validation in the MongoDB Server manual. Defaults to `False`.
`Comment`	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.
`IsOrdered`	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`.
`Let`	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.

Os seguintes exemplos de código utilizam um objeto BulkWriteOptions para executar uma operação de escrita em massa não 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

Os métodos BulkWrite() e BulkWriteAsync() retornam um objeto BulkWriteResult que contém as seguintes propriedades:

Propriedade	Descrição
`IsAcknowledged`	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.
`DeletedCount`	The number of documents deleted, if any.
`InsertedCount`	The number of documents inserted, if any.
`MatchedCount`	The number of documents matched for an update, if applicable.
`ModifiedCount`	The number of documents modified, if any.
`IsModifiedCountAvailable`	Indicates whether the modified count is available.
`Upserts`	A list that contains information about each request that resulted in an upsert operation.
`RequestCount`	The number of requests in the bulk operation.

Tratamento de exceções

Se qualquer uma das operações em uma operação de gravação em massa falhar, o Driver .NET/C# lançará um BulkWriteError e não executará nenhuma operação adicional.

Um objeto BulkWriteError contém a propriedade Index que descreve o índice da solicitação que resultou em um erro.

Informações adicionais

Para saber como realizar operações de escrita individuais, consulte os seguintes guias:

Para saber mais sobre qualquer um dos métodos ou tipos discutidos neste guia, consulte a seguinte documentação da API:

Voltar

Excluir

Leia