Substituir documentos

Nesta página

Visão geral

Dados de amostra
Operação de substituição
Exemplo de substituição de um documento
Opções
Valor de retorno
Informações adicionais
Documentação da API

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 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 .

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 Localizar 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`	Specifies whether the replace operation bypasses document validation. When set to `true`, this lets you replace a document with a new document that doesn't meet the schema validation requirements. For more information, see Schema Validation in the MongoDB Server manual. Defaults to `false`.
`collation`	Specifies the kind of language collation to use when sorting results. For more information, see Collation in the MongoDB Server manual.
`comment`	Specifies a comment of any valid BSON type to attach to the operation. Once set, this comment appears alongside records of this command in the following locations: 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 For more information, see the insert Command Fields guide in the MongoDB Server manual.
`hint`	Specifies the index to scan for documents that match the query filter. For more information, see the hint field in the MongoDB Server manual.
`let`	Specifies a document containing variables and their values to be used in the `replace_one()` method. This allows you to improve code readability by separating the variables from the operation text. Values must be constant or closed expressions that don't reference document fields. For more information, see the let field in the MongoDB Server manual.
`upsert`	Specifies whether the replace operation performs an upsert operation if no documents match the query filter. Defaults to `false`.
`write_concern`	Sets the write concern for the operation. For more information, see Write Concern in the MongoDB Server manual.

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()`	Returns the number of documents that matched the query filter, regardless of how many were replaced.
`modified_count()`	Returns number of documents modified by the replace operation. If a replaced document is identical to the original, it is not included in this count.
`result()`	Returns the bulk write result for the operation.
`upserted_id()`	Returns the ID of the document that was upserted in the database, if the driver performed an 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