Operações de gravação em massa

Nesta página

Visão geral

Dados de amostra
Criar uma instância de escrita em massa
Definir as operações de gravação
Inserir operações
Atualizar operações
Operações de substituição
Excluir operações
Executar a operação em massa
Personalizar operações de gravação em massa
Valor de retorno
Informações adicionais
Documentação da API

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

Os exemplos neste guia utilizam a coleção do restaurants no banco de dados de dados do sample_restaurants a partir dos conjuntos de dados de amostra do Atlas. Para acessar essa coleção a partir do seu aplicação C++ , instancie um mongocxx::client que se conecte a um Atlas cluster e atribua os seguintes valores às suas variáveis db e collection :

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

Para saber como criar um cluster MongoDB Atlas gratuito e carregar os conjuntos de dados de amostra, consulte o guia Iniciar com Atlas .

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

Você pode então anexar modelos de gravação à sua instância do mongocxx::bulk_write para definir a operação em massa. Para obter mais informações, consulte a seguinte seção Definir as operações de gravação .

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.
documento de atualização , que especifica o tipo de atualização a ser executada. Para obter mais informações sobre operações de atualização, consulte o guia Operadores de atualização de campo no manual do MongoDB Server .

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 .

O exemplo a seguir executa as operações de inserção, atualização, substituição e exclusão especificadas nas seções anteriores deste guia anexando cada modelo de escrita correspondente a uma instância de mongocxx::bulk_write e chamando o método execute() . Em seguida, imprime o número de documentos modificados:

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

Para saber mais sobre a função modified_count() , consulte a seção Valor de retorno deste guia.

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`	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. Defaults to `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.

O exemplo a seguir chama o método create_bulk_write() do exemplo Criar uma Instância de Gravação em Massa nesta página, mas define o campo ordered de uma instância mongocxx::options::bulk_write como 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()`	Returns the number of documents deleted, if any.
`inserted_count()`	Returns the number of documents inserted, if any.
`matched_count()`	Returns the number of documents matched for an update, if applicable.
`modified_count()`	Returns the number of documents modified, if any.
`upserted_count()`	Returns the number of documents upserted, if any.
`upserted_ids()`	Returns a map of the operation's index to the `_id` of the upserted documents, if applicable.

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