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 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 do sample_restaurants a partir do conjunto 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 MongoDB Get Started.

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.
Localização 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`	Especifica se a operação de substituição executa uma operação upsert se nenhum documento corresponder ao filtro de queries. Para obter mais informações, consulte a declaração upsert no manual do MongoDB Server. O padrão é `false`.
`bypassDocumentValidation`	Especifica se a operação de substituição ignora a validação do documento. Isso permite substituir documentos que não atendem aos requisitos de validação de esquema, se houver. Para obter mais informações sobre a validação de esquema, consulte Validação de esquema no manual do MongoDB Server. O padrão é `false`.
`collation`	Especifica o tipo de agrupamento de linguagem a ser usado ao comparar texto. Para obter mais informações, consulte agrupamentos no manual do MongoDB Server.
`hint`	Obtém ou define o índice para procurar documentos. Para obter mais informações, consulte a declaração de dica 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 inserção no manual do MongoDB Server .

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 função mongoc_collection_replace_one(), consulte a documentação API.

Voltar

Acessar dados de um cursor

Update