/ /

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 como `true`, isso permite substituir um documento por um novo documento que não atende 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 executa uma operação upsert se nenhum documento corresponder ao filtro de queries. O padrão é `false`.
`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