Operações de gravação em massa
Nesta página
Visão geral
Este guia mostra como usar o driver .NET/C# para executar operações de MongoClient
gravação em massa a partir da sua instância. Uma operação de gravação em massa é uma única chamada de banco de dados de dados que executa várias operações de gravação em uma ou mais collections do MongoDB . Isso é mais eficiente do que realizar várias operações de gravação individuais, pois reduz o número de viagens de ida e volta entre o aplicação e o banco de dados de dados.
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 BulkWriteModel
:
BulkWriteInsertOneModel<TDocument>
BulkWriteUpdateOneModel<TDocument>
BulkWriteUpdateManyModel<TDocument>
BulkWriteReplaceOneModel<TDocument>
BulkWriteDeleteOneModel<TDocument>
BulkWriteDeleteManyModel<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 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 da classe BulkWriteInsertOneModel<TDocument>
. O construtor do BulkWriteInsertOneModel<TDocument>
aceita os seguintes parâmetros:
Parâmetro | Descrição |
---|---|
collectionNamespace | The database and collection to insert the BSON document into. Data Type: string or CollectionNamespace |
document | The document to insert into the collection. Data Type: TDocument |
O exemplo seguinte cria uma instância da classe BulkWriteInsertOneModel<TDocument>
. Essa instância direciona o driver a inserir um documento no qual o campo "name"
é "Mongo's Deli"
na coleção sample_restaurants.restaurants
.
var insertOneModel = new BulkWriteInsertOneModel<BsonDocument>( "sample_restaurants.restaurants", new BsonDocument{ { "name", "Mongo's Deli" }, { "cuisine", "Sandwiches" }, { "borough", "Manhattan" }, { "restaurant_id", "1234" } } );
Dica
Insira vários documentos
Para inserir vários documentos, crie uma instância da classe BulkWriteInsertOneModel<TDocument>
para cada documento que você deseja inserir.
Atualizar operações
Para atualizar um único documento, crie uma instância da classe BulkWriteUpdateOneModel<TDocument>
. O construtor do BulkWriteUpdateOneModel<TDocument>
aceita os seguintes parâmetros:
Parâmetro | Descrição |
---|---|
collectionNamespace | The database and collection to insert the BSON document into. Data Type: string or CollectionNamespace |
filter | The query filter that specifies the criteria used to match documents in your collection.
The UpdateOne operation updates only the first document that matches the
query filter.Data Type: FilterDefinition<TDocument> |
update | The update operation you want to perform. For more information about update
operations, see Field Update Operators
in the MongoDB Server manual. Data Type: UpdateDefinition<TDocument> |
collation | Optional. The language collation to use when sorting results. See the
{+mdb+server+} manual
for more information. Data Type: Collation Default: null |
hint | Optional. The index to use to scan for documents.
See the MongoDB Server manual
for more information. Data Type: BsonValue Default: null |
isUpsert | Optional. Specifies whether the update operation performs an upsert operation if no
documents match the query filter. See the MongoDB Server manual
for more information. Data Type: boolean Default: false |
arrayFilters | Specifies which array elements to modify for an update operation on an array field.
See the MongoDB Server manual
for more information. Data Type: IEnumerable<ArrayFilterDefinition> Default: null |
No seguinte exemplo de código, o objeto BulkWriteUpdateOneModel<BsonDocument>
representa uma operação de atualização na coleção sample_restaurants.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 BulkWriteUpdateOneModel<BsonDocument>( "sample_restaurants.restaurants", 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 da classe BulkWriteUpdateManyModel<TDocument>
. O construtor desta classe aceita os mesmos parâmetros que o construtor BulkWriteUpdateOneModel<TDocument>
. A BulkWriteUpdateManyModel<TDocument>
operação atualiza todos os documentos que correspondem ao seu filtro de query.
No seguinte exemplo de código, o objeto BulkWriteUpdateManyModel<BsonDocument>
representa uma operação de atualização na coleção sample_restaurants.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 BulkWriteUpdateManyModel<BsonDocument>( "sample_restaurants.restaurants", Builders<BsonDocument>.Filter.Eq("name", "Mongo's Deli"), Builders<BsonDocument>.Update.Set("cuisine", "Sandwiches and Salads") );
Operações de substituição
Para substituir os campos em um documento, crie uma instância da classe BulkWriteReplaceOneModel<TDocument>
. O construtor do BulkWriteReplaceOneModel<TDocument>
aceita os seguintes parâmetros:
Parâmetro | Descrição |
---|---|
collectionNamespace | The database and collection to insert the BSON document into. Data Type: string or CollectionNamespace |
filter | The query filter that specifies the criteria used to match documents in your collection.
The UpdateOne operation updates only the first document that matches the
query filter.Data Type: FilterDefinition<TDocument> |
replacement | The replacement document, which specifies the fields and values to insert in the
target document. Data Type: TDocument |
collation | Optional. The language collation to use when sorting results. See
the MongoDB Server manual
for more information. Data Type: Collation Default: null |
hint | Optional. The index to use to scan for documents.
See the MongoDB Server manual
for more information. Data Type: BsonValue Default: null |
isUpsert | Optional. Specifies whether the update operation performs an upsert operation if no
documents match the query filter.
See the MongoDB Server manual
for more information. Data Type: boolean Default: false |
No exemplo a seguir, o objeto BulkWriteReplaceOneModel<BsonDocument>
representa uma operação de substituição na coleção sample_restaurants.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 BulkWriteReplaceOneModel<BsonDocument>( "sample_restaurants.restaurants", Builders<BsonDocument>.Filter.Eq("restaurant_id", "1234"), new BsonDocument{ { "name", "Mongo's Pizza" }, { "cuisine", "Pizza" }, { "borough", "Brooklyn" }, { "restaurant_id", "5678" } } );
Dica
Substituir vários documentos
Para substituir vários documentos, crie uma instância da classe BulkWriteReplaceOneModel<TDocument>
para cada documento que deseja substituir.
Excluir operações
Para excluir um documento, crie uma instância da classe BulkWriteDeleteOneModel<TDocument>
. O construtor do BulkWriteDeleteOneModel<TDocument>
aceita os seguintes parâmetros:
Parâmetro | Descrição |
---|---|
collectionNamespace | The database and collection to insert the BSON document into. Data Type: string or CollectionNamespace |
filter | The query filter that specifies the criteria used to match documents in your collection.
The DeleteOne operation deletes only the first document that matches the
query filter.Data Type: FilterDefinition<TDocument> |
collation | Optional. The language collation to use when sorting results. See
the MongoDB Server manual
for more information. Data Type: Collation Default: null |
hint | Optional. The index to use to scan for documents.
See the MongoDB Server manual
for more information. Data Type: BsonValue Default: null |
No seguinte exemplo de código, o objeto BulkWriteDeleteOneModel<BsonDocument>
representa uma operação de exclusão na coleção sample_restaurants.restaurants
. A operação corresponde e exclui o primeiro documento onde o valor do campo restaurant_id
é "5678"
.
var deleteOneModel = new BulkWriteDeleteOneModel<BsonDocument>( "sample_restaurants.restaurants", Builders<BsonDocument>.Filter.Eq("restaurant_id", "5678") );
Para excluir vários documentos, crie uma instância da classe BulkWriteDeleteManyModel<TDocument>
e passe um filtro de query que especifique o documento que você deseja excluir. A DeleteMany
operação remove todos os documentos que correspondem ao seu filtro de query.
No seguinte exemplo de código, o objeto BulkWriteDeleteManyModel<BsonDocument>
representa uma operação de exclusão na coleção sample_restaurants.restaurants
. A operação corresponde e exclui todos os documentos onde o valor do campo name
é "Mongo's Deli"
.
var deleteManyModel = new BulkWriteDeleteManyModel<BsonDocument>( "sample_restaurants.restaurants", Builders<BsonDocument>.Filter.Eq("name", "Mongo's Deli") );
Executar as operações de gravação
Após definir uma instância BulkWriteModel
para cada operação que deseja executar, crie uma instância de uma classe que implemente a interface IReadOnlyList
. Adicione seus BulkWriteModel
objetos a este IReadOnlyList
e, em seguida, passe o IReadOnlyList
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 coleção.
Dica
IReadOnlyList
Array
e List
são duas classes comuns que implementam a interface do IReadOnlyList
.
Selecione a partir das seguintes guias para visualizar como utilizar o método BulkWriteAsync()
assíncrono e o método BulkWrite()
síncrono para executar uma operação de gravação em massa.
var client = new MongoClient("mongodb://localhost:27017"); var collection = "sample_restaurants.restaurants"; var bulkWriteModels = new[] { new BulkWriteInsertOneModel<BsonDocument>( collection, new BsonDocument{ { "name", "Mongo's Deli" }, { "cuisine", "Sandwiches" }, { "borough", "Manhattan" }, { "restaurant_id", "1234" } } ), new BulkWriteInsertOneModel<BsonDocument>( collection, new BsonDocument{ { "name", "Mongo's Deli" }, { "cuisine", "Sandwiches" }, { "borough", "Brooklyn" }, { "restaurant_id", "5678" } } ), new BulkWriteUpdateManyModel<BsonDocument>( collection, Builders<BsonDocument>.Filter.Eq("name", "Mongo's Deli"), Builders<BsonDocument>.Update.Set("cuisine", "Sandwiches and Salads") ), new BulkWriteDeleteOneModel<BsonDocument>( collection, Builders<BsonDocument>.Filter.Eq("restaurant_id", "1234") ) }; var results = await client.BulkWriteAsync(bulkWriteModels); Console.WriteLine("Bulk write results: " + results);
var client = new MongoClient("mongodb://localhost:27017"); var collection = "sample_restaurants.restaurants"; var bulkWriteModels = new[] { new BulkWriteInsertOneModel<BsonDocument>( collection, new BsonDocument{ { "name", "Mongo's Deli" }, { "cuisine", "Sandwiches" }, { "borough", "Manhattan" }, { "restaurant_id", "1234" } } ), new BulkWriteInsertOneModel<BsonDocument>( collection, new BsonDocument{ { "name", "Mongo's Deli" }, { "cuisine", "Sandwiches" }, { "borough", "Brooklyn" }, { "restaurant_id", "5678" } } ), new BulkWriteUpdateManyModel<BsonDocument>( collection, Builders<BsonDocument>.Filter.Eq("name", "Mongo's Deli"), Builders<BsonDocument>.Update.Set("cuisine", "Sandwiches and Salads") ), new BulkWriteDeleteOneModel<BsonDocument>( collection, Builders<BsonDocument>.Filter.Eq("restaurant_id", "1234") ) }; var results = client.BulkWrite(bulkWriteModels); Console.WriteLine("Bulk write results: " + results);
Os exemplos de código anteriores produzem a seguinte saída:
BulkWriteResult({'writeErrors': [], 'writeConcernErrors': [], 'nInserted': 2, 'nUpserted': 0, 'nMatched': 2, 'nModified': 2, 'nRemoved': 1, 'upserted': []}, acknowledged=True)
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 ClientBulkWriteOptions
. A classe ClientBulkWriteOptions
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. |
VerboseResult | Specifies whether the ClientBulkWriteResult object returned by the operation
includes detailed results for each successful write operation.Defaults to false . |
WriteConcern | The write concern to use for the write operation, as a value from the WriteConcern
enum.Defaults to the write concern of the collection on which the operation is running. |
Os seguintes exemplos de código utilizam um objeto ClientBulkWriteOptions
para personalizar uma operação de exclusão:
var client = new MongoClient("mongodb://localhost:27017"); var deleteOneModel = new BulkWriteDeleteOneModel<BsonDocument>( "sample_restaurants.restaurants", Builders<BsonDocument>.Filter.Eq("restaurant_id", "5678") ); var clientBulkWriteOptions = new ClientBulkWriteOptions { IsOrdered = false, WriteConcern = WriteConcern.Unacknowledged, VerboseResult = true }; var results = await client.BulkWriteAsync(deleteOneModel, clientBulkWriteOptions);
var client = new MongoClient("mongodb://localhost:27017"); var deleteOneModel = new BulkWriteDeleteOneModel<BsonDocument>( "sample_restaurants.restaurants", Builders<BsonDocument>.Filter.Eq("restaurant_id", "5678") ); var clientBulkWriteOptions = new ClientBulkWriteOptions { IsOrdered = false, WriteConcern = WriteConcern.Unacknowledged, VerboseResult = true }; var results = client.BulkWrite(deleteOneModel, clientBulkWriteOptions);
Valor de retorno
Os métodos BulkWrite()
e BulkWriteAsync()
retornam um objeto ClientBulkWriteResult
que contém as seguintes propriedades:
Propriedade | Descrição |
---|---|
Acknowledged | 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 ClientBulkWriteResult object, the driver throws an exception. |
DeleteResults | An IReadOnlyDictionary<int, BulkWriteDeleteResult> object containing the
results of each successful delete operation, if any. |
DeletedCount | The number of documents deleted, if any. |
InsertResults | An IReadOnlyDictionary<int, BulkWriteInsertOneResult> object containing the
results of each successful insert operation, 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. |
UpsertResults | An IReadOnlyDictionary<int, BulkWriteUpdateResult> object containing the
results of each successful update operation, if any. |
UpsertedCount | The number of documents upserted, if any. |
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 ClientBulkWriteException
e não executará nenhuma operação adicional.
Um objeto ClientBulkWriteException
contém as seguintes propriedades:
Propriedade | Descrição |
---|---|
connectionId | |
message | The error message. Data Type: string |
writeErrors | A dictionary of errors that occurred during the bulk write operation. Data Type: IReadOnlyDictionary<int, WriteError> |
partialResult | The results of any successful operations performed before the exception was thrown. Data Type: ClientBulkWriteResult |
writeConcernErrors | Write concern errors that occurred during execution of the bulk write operation. Data Type: IReadOnlyList<MongoWriteConcernException> |
innerException |
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: