/ /

Operações de gravação em massa

Visão geral

Neste guia, você aprenderá a executar várias operações de gravação em uma única chamada de banco de dados de dados usando operações de gravação em massa.

Considere um cenário no qual você deseja inserir um documento em uma coleção, atualizar vários outros documentos e excluir um documento. Se você usar métodos individuais, cada operação exigirá sua própria chamada de banco de dados de dados. Em vez disso, você pode usar uma operação em massa para reduzir o número de chamadas para o banco de dados de dados.

Dados de amostra

The examples in this guide use the restaurants collection in the sample_restaurants database from the Atlas sample datasets. To access this collection from your C++ application, instantiate a mongocxx::client that connects to an Atlas cluster and assign the following values to your db and collection variables:

auto db = client["sample_restaurants"];
auto collection = db["restaurants"];

Para aprender a criar um cluster MongoDB Atlas gratuito e carregar os conjuntos de dados de amostra, consulte o Guia de Introdução do MongoDB.

Criar uma instância de escrita em massa

Antes de executar uma operação de escrita em massa, chame o método create_bulk_write() em uma collection. Este método retorna uma instância da classe mongocxx::bulk_write que você pode utilizar para armazenar instruções sobre quais tipos de gravações em massa devem ser executadas.

O exemplo a seguir chama o método create_bulk_write() na coleção restaurants :

auto bulk = collection.create_bulk_write();

You can then append write models to your mongocxx::bulk_write instance to define the bulk operation. For more information, see the following Define the Write Operations section.

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 de modelo:

mongocxx::model::insert_one
mongocxx::model::update_one
mongocxx::model::update_many
mongocxx::model::replace_one
mongocxx::model::delete_one
mongocxx::model::delete_many

Em seguida, anexe cada modelo de gravação à instância mongocxx::bulk_write retornada pelo método create_bulk_write() .

As seções a seguir mostram como criar e usar instâncias das classes de modelo de escrita anteriores.

Inserir operações

Para executar uma operação de inserção, crie uma instância da classe mongocxx::model::insert_one e especifique o documento que você deseja inserir. Em seguida, anexe a instância de modelo a uma instância da classe mongocxx::bulk_write .

O exemplo seguinte cria uma instância de mongocxx::model::insert_one e a anexa a uma instância do mongocxx::bulk_write denominada bulk:

auto insert_doc = make_document(kvp("name", "Mongo's Deli"),
                                kvp("cuisine", "Sandwiches"),
                                kvp("borough", "Manhattan"),
                                kvp("restaurant_id", "1234"));
mongocxx::model::insert_one insert_op{insert_doc.view()};
bulk.append(insert_op);

Para inserir vários documentos, crie uma instância de mongocxx::model::insert_one para cada documento.

Atualizar operações

Para atualizar um documento, crie uma instância de mongocxx::model::update_one. Este modelo instrui o driver a atualizar o primeiro documento que corresponda ao seu filtro de query. Em seguida, anexe a instância de modelo a uma instância da classe mongocxx::bulk_write .

Passe os seguintes argumentos para o modelo mongocxx::model::update_one :

documento de filtro de query , que especifica os critérios utilizados para corresponder aos documentos em sua coleção.
Update document, which specifies the kind of update to perform. For more information about update operations, see the Field Update Operators guide in the MongoDB Server manual.

O exemplo seguinte cria uma instância de mongocxx::model::update_one e a anexa a uma instância do mongocxx::bulk_write denominada bulk:

auto filter_doc = make_document(kvp("name", "Mongo's Deli"));
auto update_doc = make_document(kvp("$set", make_document(kvp("cuisine", "Sandwiches and Salads"))));
mongocxx::model::update_one update_op{filter_doc.view(), update_doc.view()};
bulk.append(update_op);

Para atualizar vários documentos, crie uma instância de mongocxx::model::update_many e passe os mesmos argumentos. Esse modelo instrui o driver a atualizar todos os documentos que correspondem ao seu filtro de query.

O exemplo seguinte cria uma instância de mongocxx::model::update_many e a anexa a bulk:

auto filter_doc = make_document(kvp("name", "Mongo's Deli"));
auto update_doc = make_document(kvp("$set", make_document(kvp("cuisine", "Sandwiches and Salads"))));
mongocxx::model::update_many update_op{filter_doc.view(), update_doc.view()};
bulk.append(update_op);

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. Para executar uma operação de substituição, crie uma instância da classe mongocxx::model::replace_one e passe um filtro de query e os campos e valores que você deseja armazenar no documento correspondente. Em seguida, anexe a instância de modelo a uma instância da classe mongocxx::bulk_write .

O exemplo seguinte cria uma instância de mongocxx::model::replace_one e a anexa a uma instância do mongocxx::bulk_write denominada bulk:

auto filter_doc = make_document(kvp("restaurant_id", "1234"));
auto replace_doc = make_document(kvp("name", "Mongo's Deli"),
                                kvp("cuisine", "Sandwiches and Salads"),
                                kvp("borough", "Brooklyn"),
                                kvp("restaurant_id", "5678"));
mongocxx::model::replace_one replace_op{filter_doc.view(), replace_doc.view()};
bulk.append(replace_op);

Para substituir vários documentos, você deve criar uma nova instância de mongocxx::model::replace_one para cada documento.

Excluir operações

Para excluir um documento, crie uma instância da classe mongocxx::model::delete_one e passe um filtro de query especificando o documento que você deseja excluir. Esse modelo instrui o driver a excluir apenas o primeiro documento que corresponde ao seu filtro de query. Em seguida, anexe a instância de modelo a uma instância da classe mongocxx::bulk_write .

O exemplo seguinte cria uma instância de mongocxx::model::delete_one e a anexa a uma instância do mongocxx::bulk_write denominada bulk:

auto filter_doc = make_document(kvp("restaurant_id", "5678"));
mongocxx::model::delete_one delete_op{filter_doc.view()};
bulk.append(delete_op);

Para excluir vários documentos, crie uma instância da classe mongocxx::model::delete_many e passe um filtro de query especificando o documento que deseja excluir. Esse modelo instrui o driver a excluir todos os documentos que correspondam ao seu filtro de query.

O exemplo seguinte cria uma instância de mongocxx::model::delete_many e a anexa a bulk:

auto filter_doc = make_document(kvp("borough", "Manhattan"));
mongocxx::model::delete_many delete_op{filter_doc.view()};
bulk.append(delete_op);

Executar a operação em massa

Para executar uma operação em massa, chame o método execute() em uma instância da classe mongocxx::bulk_write que contém seus modelos de escrita. Por padrão, o método execute() executa as operações na ordem em que são anexadas à instância do mongocxx::bulk_write .

The following example performs the insert, update, replace, and delete operations specified in the preceding sections of this guide by appending each corresponding write model to an instance of mongocxx::bulk_write and calling the execute() method. Then, it prints the number of modified documents:

auto bulk = collection.create_bulk_write();
// Specifies documents to insert, update, replace, or delete
auto insert_doc = make_document(kvp("name", "Mongo's Deli"),
                                kvp("cuisine", "Sandwiches"),
                                kvp("borough", "Manhattan"),
                                kvp("restaurant_id", "1234"));
auto update_filter = make_document(kvp("name", "Mongo's Deli"));
auto update_doc = make_document(kvp("$set", make_document(kvp("cuisine", "Sandwiches and Salads"))));
auto replace_filter = make_document(kvp("restaurant_id", "1234"));
auto replace_doc = make_document(kvp("name", "Mongo's Deli"),
                                kvp("cuisine", "Sandwiches and Salads"),
                                kvp("borough", "Brooklyn"),
                                kvp("restaurant_id", "5678"));
auto delete_filter = make_document(kvp("borough", "Manhattan"));
// Creates write models for each write operation using the preceding documents
mongocxx::model::insert_one insert_op{insert_doc.view()};
mongocxx::model::update_many update_op{update_filter.view(), update_doc.view()};
mongocxx::model::replace_one replace_op{replace_filter.view(), replace_doc.view()};
mongocxx::model::delete_many delete_op{delete_filter.view()};
// Appends each write model to the bulk operation
bulk.append(insert_op);
bulk.append(update_op);
bulk.append(replace_op);
bulk.append(delete_op);
// Runs the bulk operation
auto result = bulk.execute();
std::cout << "Modified documents: " << result->modified_count() << std::endl;

Modified documents: 2

Se qualquer uma das operações de gravação falhar, o driver C++ emitirá um mongocxx::bulk_write_exception e não executará mais nenhuma operação.

Dica

To learn more about the modified_count() function, see the Return Value section of this guide.

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

Você pode modificar o comportamento do método create_bulk_write() passando uma instância da classe mongocxx::options::bulk_write como parâmetro. A tabela seguinte descreve os campos que você pode definir em uma instância do mongocxx::options::bulk_write :

Campo	Descrição
`ordered`	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. O padrão é `true`.
`bypass_document_validation`	Specifies whether the operation bypasses document-level validation. For more information, see Schema Validation in the MongoDB Server manual. Defaults to `false`.
`write_concern`	Specifies the write concern for the bulk operation. For more information, see Write Concern in the MongoDB Server manual.
`comment`	Attaches a comment to the operation. For more information, see the delete command fields guide in the MongoDB Server manual.
`let`	Specifies a document with a list of values to improve operation readability. 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.

The following example calls the create_bulk_write() method from the Create a Bulk Write Instance example on this page, but sets the ordered field of a mongocxx::options::bulk_write instance to false:

mongocxx::options::bulk_write opts;
opts.ordered(false);
auto bulk = collection.create_bulk_write(opts);

Se qualquer uma das operações de escrita em uma escrita em massa não ordenada falhar, o driver C++ relatará os erros somente após tentar todas as operações.

Observação

Operações em massa não ordenadas não garantem ordem de execução. A ordem pode ser diferente da forma como você os lista para otimizar o tempo de execução.

Valor de retorno

O método execute() retorna uma instância da classe mongocxx::result::bulk_write . A classe mongocxx::result::bulk_write contém as seguintes funções de membro:

Função	Descrição
`deleted_count()`	Retorna o número de documentos excluídos, se houver.
`inserted_count()`	Retorna o número de documentos inseridos, se houver.
`matched_count()`	Retorna o número de documentos correspondentes para uma atualização, se aplicável.
`modified_count()`	Retorna o número de documentos modificados, se houver.
`upserted_count()`	Retorna o número de documentos atualizados, se houver.
`upserted_ids()`	Retorna um mapa do índice da operação para o `_id` dos documentos atualizados, se aplicável.

Informações adicionais

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

Documentação da API

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

Voltar

Excluir

GridFS