/ /

Substituir documentos

Visão geral

Neste guia, você pode aprender como usar o driver C++ para executar uma operação de substituição em uma coleção MongoDB . Uma operação de substituição remove todos os campos, exceto o campo _id no documento de destino, e os substitui por novos. Você pode chamar o método replace_one() para substituir um único documento.

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.

Operação de substituição

Você pode executar uma operação de substituição chamando o método replace_one(). Esse método remove todos os campos, exceto o campo _id do primeiro documento que corresponde aos critérios de pesquisa. Em seguida, ele insere os campos e valores especificados no documento.

O método replace_one() exige os seguintes parâmetros:

documento de filtro de query : especifica qual documento substituir. Para obter mais informações sobre filtros de query, consulte Documentos de filtro de query no manual do MongoDB Server .
Substituir documento: Especifica os campos e valores a serem inseridos no novo documento.

Importante

Os valores dos campos _id são imutáveis. Se o documento de substituição especificar um valor para o campo _id, ele deverá corresponder ao valor _id do documento existente.

Exemplo de substituição de um documento

O exemplo a seguir usa o replace_one() método para substituir um documento com um name valor de campo de "Nobu" por um novo documento com um name valor de campo de "La Bernadin":

auto query_filter = make_document(kvp("name", "Nobu"));
auto replace_doc = make_document(kvp("name", "La Bernadin"));
auto result = collection.replace_one(query_filter.view(), replace_doc.view());

Para verificar se você substituiu o documento com sucesso, você pode usar o método find_one() para imprimir o novo documento:

auto new_doc = collection.find_one(make_document(kvp("name", "La Bernadin")));
std::cout << "New document: " << bsoncxx::to_json(*new_doc) << std::endl;

New document: { "_id" : { "$oid" : "..." }, "name" : "La Bernadin" }

Para saber mais sobre o método find_one() , consulte Encontrar um documento no guia Recuperar dados.

Opções

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

Campo	Descrição
`bypass_document_validation`	Especifica se a operação de substituição ignora a validação do documento . Quando definido `true` como, isso permite substituir um documento por um novo documento que não atenda aos requisitos de validação de esquema . Para obter mais informações, consulte Validação de esquema no manual do MongoDB Server . O padrão `false` é.
`collation`	Especifica o tipo de agrupamento de idiomas a ser usado ao classificar os resultados. Para obter mais informações, consulte Agrupamento no manual do MongoDB Server .
`comment`	Especifica um comentário de qualquer tipo BSON válido para anexar à operação. Uma vez definido, este comentário aparece ao lado dos registros deste comando nos seguintes locais: mensagens de log do mongod, no `attr.command.cursor.comment` campo Saída do profiler de banco de dados, no `system.profile.command` `comment` campo `currentOp` Saída no `currentOp.command` `comment` campo Para obter mais informações, consulte o guia de inserção de campos de comando no manual do MongoDB Server .
`hint`	Especifica o índice a ser analisado em busca de documentos que correspondam ao query filter. Para obter mais informações, consulte o campo dica no manual do MongoDB Server .
`let`	Especifica um documento contendo variáveis e seus valores a serem utilizados no método `replace_one()`. Isso permite que você melhore a legibilidade do código separando as variáveis do texto 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 o campo let no manual do MongoDB Server .
`upsert`	Especifica se a operação de substituição executará uma operação de upsert se nenhum documento corresponder ao filtro de consulta. `false`Padrão é.
`write_concern`	Define a preocupação de gravação para a operação. Para obter mais informações, consulte Write Concern no manual do MongoDB Server .

Exemplo: Opção de dica

O exemplo seguinte utiliza o método create_index() para criar um índice de campo único ascendente no campo name. Em seguida, ele passa um objeto mongocxx::options::replace para o método replace_one() após definir seu campo hint para o novo índice. Isso instrui a operação de substituição a pesquisar o índice do campo name ao substituir um documento que tenha um valor de campo name de "Nobu":

auto index_specification = make_document(kvp("name", 1));
collection.create_index(index_specification.view());
mongocxx::options::replace opts{}; 
opts.hint(mongocxx::hint{"name_1"});
auto query_filter = make_document(kvp("name", "Nobu"));
auto replace_doc = make_document(kvp("name", "La Bernadin"));
auto result = collection.replace_one(query_filter.view(), replace_doc.view(), opts);

Para saber mais sobre índices, consulte o guia Otimizar queries com índices.

Exemplo: opção upsert

O exemplo a seguir passa um objeto mongocxx::options::replace para o método replace_one() depois de definir seu valor de campo upsert como true. Como nenhum documento corresponde ao filtro de query, isso instrui a operação de substituição a inserir um novo documento com um valor de campo name de "Shake Shack" na coleção:

std::cout << "Total document count before replace_one(): " << collection.count_documents({}) << std::endl;
mongocxx::options::replace opts{}; 
opts.upsert(true);
auto query_filter = make_document(kvp("name", "In-N-Out Burger"));
auto replace_doc = make_document(kvp("name", "Shake Shack"));
auto result = collection.replace_one(query_filter.view(), replace_doc.view(), opts);
std::cout << "Total document count after replace_one(): " << collection.count_documents({}) << std::endl;

Total document count before replace_one(): 25359
Total document count after replace_one(): 25360

Valor de retorno

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

Função	Descrição
`matched_count()`	Retorna o número de documentos que corresponderam ao filtro de query, independentemente de quantos foram substituídos.
`modified_count()`	Retorna o número de documentos modificados pela operação de substituição. Se um documento substituído for idêntico ao original, ele não será incluído nesta contagem.
`result()`	Retorna o resultado da gravação em massa para a operação.
`upserted_id()`	Retorna a ID do documento que foi atualizado no banco de dados, se o driver tiver realizado um upsert.

Exemplo: matched_count()

O exemplo a seguir usa o replace_one() método para substituir um documento name "Shake Shack" com um valor de campo name de "In-N-Out Burger". Em seguida, ele chama a função de membro matched_count() para imprimir o número de documentos que correspondem ao filtro de query:

auto query_filter = make_document(kvp("name", "Shake Shack"));
auto replace_doc = make_document(kvp("name", "In-N-Out Burger"));
auto result = collection.replace_one(query_filter.view(), replace_doc.view());
std::cout << "Matched documents: " << result->matched_count() << std::endl;

Matched documents: 11

Exemplo: upserted_id()

O exemplo a seguir usa o método replace_one() para substituir um documento que tenha um valor de campo name de "In-N-Out Burger". Como a opção upsert está definida como true, o driver C++ insere um novo documento quando o filtro de query não corresponde a nenhum documento existente. Em seguida, o código chama a função de membro upserted_id() para imprimir o valor de campo _id do documento atualizado:

mongocxx::options::replace opts{}; 
opts.upsert(true);
auto query_filter = make_document(kvp("name", "In-N-Out Burger"));
auto replace_doc = make_document(kvp("name", "Shake Shack"));
auto result = collection.replace_one(query_filter.view(), replace_doc.view(), opts);
auto id = result->upserted_id()->get_value();
        
std::cout << "Upserted ID: " << id.get_oid().value.to_string() << std::endl;

// Your ID value may differ
Upserted ID: 67128c5ecc1f8c15ea26fcf8

Informações adicionais

Para saber mais sobre como criar filtros de queries, consulte o guia Especifique uma consulta.

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

Update

Excluir