Substituir documentos

Nesta página

Visão geral

Dados de amostra
Operação de substituição
Parâmetros necessários
Exemplo
Modificar a operação de substituição
Exemplo de opções de substituição
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 tem desempenho diferente de uma operação de atualização. Uma operação de atualização modifica somente os campos especificados em um documento de destino. Uma operação de substituição remove todos os campos do documento de destino e os substitui por novos.

Para substituir um documento, use a função mongoc_collection_replace_one().

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 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 usando mongoc_collection_replace_one(). Esta função 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.

Parâmetros necessários

A função mongoc_collection_replace_one() exige os seguintes parâmetros:

Collection: especifica a collection na qual executar a operação de substituição.
documento de filtro de query : especifica quais documentos de coleção devem ser correspondidos. A função seleciona o primeiro documento correspondente a ser substituído. Para obter mais informações sobre filtros de query, consulte a seção Documentos de filtro de query no manual do MongoDB Server .
documento de substituição: Especifica os campos e valores a serem inseridos no novo documento.
documento de opções : especifica opções para personalizar a operação, ou NULL.
Localização dos resultados: especifica um ponteiro para o armazenamento substituível que conterá os resultados da operação ou NULL.
Local do erro: especifica um local para um valor de erro ou NULL.

Exemplo

O exemplo a seguir usa a função mongoc_collection_replace_one() para substituir os campos e valores de um documento em que o valor de campo name é "Pizza Town" por um documento em que o valor de campo name é "Mongo's Pizza":

bson_t *query = BCON_NEW ("name", "Pizza Town");
bson_t *replace = BCON_NEW (
    "name", "Mongo's Pizza",
    "cuisine", "Pizza",
    "address", "{",
    "street", "123 Pizza St",
    "zipCode", "10003",
    "}",
    "borough", "Manhattan"
);
bson_error_t error;
if (!mongoc_collection_replace_one (collection, query, replace, NULL, NULL, &error)) {
    fprintf (stderr, "Replace operation failed: %s\n", error.message);
}
bson_destroy (query);
bson_destroy (replace);

Importante

Os valores de _id campos são imutáveis. Se o seu documento de substituição especificar um valor para o campo _id, ele deverá ser idêntico ao valor _id do documento existente.

Modificar a operação de substituição

Você pode modificar o comportamento da função mongoc_collection_replace_one() passando um documento BSON que especifica os valores das opções. A tabela a seguir descreve algumas opções que você pode definir no documento:

Opção	Descrição
`upsert`	Specifies whether the replace operation performs an upsert operation if no documents match the query filter. For more information, see the upsert statement in the MongoDB Server manual. Defaults to `false`.
`bypassDocumentValidation`	Specifies whether the replace operation bypasses document validation. This lets you replace documents that don't meet the schema validation requirements, if any exist. For more information about schema validation, see Schema Validation in the MongoDB Server manual. Defaults to `false`.
`collation`	Specifies the kind of language collation to use when comparing text. For more information, see Collation in the MongoDB Server manual.
`hint`	Gets or sets the index to scan for documents. For more information, see the hint statement in the MongoDB Server manual.
`comment`	Attaches a comment to the operation. For more information, see the insert command fields guide in the MongoDB Server manual.

Exemplo de opções de substituição

O código a seguir usa a função mongoc_collection_replace_one() para localizar o primeiro documento no qual o campo name tem o valor "Food Town" e, em seguida, substitui esse documento por um novo documento no qual o valor name é "Food World". Como a opção upsert está definida como true, o driver insere um novo documento se o filtro de query não corresponder a nenhum documento existente:

bson_t *query = BCON_NEW ("name", "Food Town");
bson_t *replace = BCON_NEW (
    "name", "Food World",
    "cuisine", "Mixed",
    "address", "{",
    "street", "123 Food St",
    "zipCode", "10003",
    "}",
    "borough", "Manhattan"
);
bson_error_t error;
bson_t opts;
bson_init (&opts);
bson_append_bool (&opts, "upsert", -1, true);
if (!mongoc_collection_replace_one (collection, query, replace, &opts, NULL, &error)) {
    fprintf (stderr, "Replace operation failed: %s\n", error.message);
} 
bson_destroy (query);
bson_destroy (replace);
bson_destroy (&opts);

Informações adicionais

Para saber mais sobre as operações de atualização, consulte o guia Atualizar documentos .

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

Documentação da API

Para saber mais sobre a mongoc_collection_replace_one() função, consulte a documentação API.

Voltar

Insert

Update