Menu Docs
Página inicial do Docs
/ / /
C#/.NET
/ / /

Operações de gravação em massa

Nesta página

  • Visão geral
  • Dados de amostra
  • Definir as operações de gravação
  • Inserir operações
  • Atualizar operações
  • Operações de substituição
  • Excluir operações
  • Executar as operações de gravação
  • Personalizar operações de gravação em massa
  • Valor de retorno
  • Tratamento de exceções
  • Informações adicionais

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.

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.

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.

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

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.

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.

update

The update operation you want to perform. For more information about update operations, see Field Update Operators in the MongoDB Server manual.

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.

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")
);

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.

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.

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.

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")
);

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)

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);

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.

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

The connection identifier.

Data Type: 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.

writeConcernErrors

Write concern errors that occurred during execution of the bulk write operation.

Data Type: IReadOnlyList<MongoWriteConcernException>

innerException

The inner exception.

Data Type: Exception

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