Replace Documents

For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

Replace Documents

Overview

In this guide, you can learn how to use the C driver to run a replace operation on a MongoDB collection. A replace operation performs differently than an update operation. An update operation modifies only the specified fields in a target document. A replace operation removes all fields in the target document and replaces them with new ones.

To replace a document, use the mongoc_collection_replace_one() function.

Sample Data

The examples in this guide use the restaurants collection in the sample_restaurants database from the Atlas sample datasets. To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the MongoDB Get Started guide.

Replace Operation

You can perform a replace operation by using mongoc_collection_replace_one(). This function removes all fields except the _id field from the first document that matches the search criteria. It then inserts the fields and values you specify into the document.

Required Parameters

The mongoc_collection_replace_one() function requires the following parameters:

• Collection: Specifies the collection on which to perform the replace operation.

• Query filter document: Specifies which collection documents to match. The function selects the first matching document to replace. For more information about query filters, see the [Query Filter Documents section](https://www.mongodb.com/docs/manual/core/document/#query-filter-documents in the MongoDB Server manual.

• Replacement document: Specifies the fields and values to insert into the new document.

• Options document: Specifies options to customize the operation, or NULL.

• Results location: Specifies a pointer to overwritable storage that will contain operation results, or NULL.

• Error location: Specifies a location for an error value, or NULL.

Example

The following example uses the mongoc_collection_replace_one() function to replace the fields and values of a document in which the name field value is “Pizza Town” with a document in which the name field value is “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);

Important:

The values of _id fields are immutable. If your replacement document specifies a value for the _id field, it must be identical to the _id value of the existing document.

Modify the Replace Operation

You can modify the behavior of the mongoc_collection_replace_one() function by passing a BSON document that specifies option values. The following table describes some options you can set in the document:

Replace Options Example

The following code uses the mongoc_collection_replace_one() function to find the first document in which the name field has the value “Food Town”, then replaces this document with a new document in which the name value is “Food World”. Because the upsert option is set to true, the driver inserts a new document if the query filter doesn't match any existing documents:

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);

Additional Information

To learn more about update operations, see the [Update Documents](https://www.mongodb.com/docs/languages/c/c-driver/current/crud/update.md#std-label-c-write-update guide.

To learn more about creating query filters, see the [Specify a Query](https://www.mongodb.com/docs/languages/c/c-driver/current/crud/query-operations/specify-a-query.md#std-label-c-specify-query guide.

API Documentation

To learn more about the mongoc_collection_replace_one() function, see the API documentation.