Replace Documents

On this page

Overview

Sample Data
Replace Operation
Required Parameters
Example
Modify the Replace Operation
Replace Options Example
Additional Information
API Documentation

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 Get Started with Atlas 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 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:

Option	Description
`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.

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

To learn more about creating query filters, see the Specify a Query guide.

API Documentation

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

Back

Insert

Update