/ /

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

Os exemplos neste guia usam a collection restaurants no banco de dados sample_restaurants dos conjuntos de banco 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 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();

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`	`true`Se, 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. `false`Se, o driver executará as operações em uma ordem arbitrária e tentará executar todas as operações. O padrão `true` é.
`bypass_document_validation`	Especifica se a operação ignora a validação em nível de documento. Para obter mais informações, consulte Validação de esquema no manual do MongoDB Server . O padrão `false` é.
`write_concern`	Especifica a preocupação de gravação para a operação em massa. Para obter mais informações, consulte Write Concern no manual do MongoDB Server .
`comment`	Anexa um comentário à operação. Para obter mais informações, consulte o guia de campos de comando de exclusão no manual do MongoDB Server .
`let`	Especifica um documento com uma lista de valores para melhorar a legibilidade da operação. 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 .

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