/ /

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 executar 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 gratuito do MongoDB Atlas e carregar os conjuntos de dados de amostra, consulte o tutorial 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`	Especifica se a operação ignora a validação no nível do documento. Para obter mais informações, consulte validação de esquema no manual do MongoDB Server. O padrão é `False`.
`Comment`	Um comentário a ser anexado à operação, na forma de um `BsonValue`. Para obter mais informações, consulte o guia excluir campos de comando no manual do MongoDB Server.
`IsOrdered`	Se `True`, o driver executa as operações de gravação na ordem fornecida. Se ocorrer um erro, as operações restantes não serão tentadas. Se `False`, o driver executa as operações em uma ordem arbitrária e tenta executar todas as operações. Se alguma das operações de gravação em uma gravação em massa não ordenada falhar, o driver relatará os erros somente depois de tentar todas as operações. O padrão é `True`.
`Let`	Um mapa de nomes e valores de parâmetros, na forma de um `BsonDocument`. Os valores devem ser expressões constantes ou fechadas que não façam referência aos campos do documento . Para obter mais informações, consulte a declaração let no manual do MongoDB Server .

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`	Indica se o servidor reconheceu a operação de gravação em massa. Se o valor desta propriedade for `False` e você tentar acessar qualquer outra propriedade do objeto `BulkWriteResult`, o driver lançará uma exceção.
`DeletedCount`	O número de documentos excluídos, se houver.
`InsertedCount`	O número de documentos inseridos, se houver.
`MatchedCount`	O número de documentos correspondentes para uma atualização, se aplicável.
`ModifiedCount`	O número de documentos modificados, se houver.
`IsModifiedCountAvailable`	Indica se a contagem modificada está disponível.
`Upserts`	Uma lista que contém informações sobre cada solicitação que resultou em uma operação de upsert.
`RequestCount`	O número de solicitações na operação em massa.

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