Bulk Write Operations

On this page

Overview

Sample Data
Start the Bulk Write Operation
Define the Write Operations
Insert Operations
Update Operations
Replace Operations
Delete Operations
Run the Bulk Operation
Customize Bulk Write Operations
Additional Information
API Documentation

Overview

In this guide, you can learn how to perform multiple write operations in a single database call by using bulk write operations.

Consider a scenario in which you want to insert a document into a collection, update multiple other documents, then delete a document. If you use individual functions, each operation requires its own database call. Instead, you can use a bulk operation to reduce the number of calls to the database.

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.

Start the Bulk Write Operation

Before running a bulk write operation, call the mongoc_collection_create_bulk_operation_with_opts() function. This function returns a value of type mongoc_bulk_operation_t that you can use to store instructions about which bulk writes to perform.

The mongoc_collection_create_bulk_operation_with_opts() function accepts the following parameters:

Collection: Specifies the collection to modify
Options document: Specifies options to customize the operation, or NULL

The following example calls the mongoc_collection_create_bulk_operation_with_opts() function and passes the restaurants collection as a parameter:

mongoc_bulk_operation_t *bulk =
   mongoc_collection_create_bulk_operation_with_opts (collection, NULL);

You can then add write instructions to the bulk operation. For more information, see the following Define the Write Operations section.

Define the Write Operations

You can define a write operation and add it to the bulk write by calling the following methods:

mongoc_bulk_operation_insert_with_opts()
mongoc_bulk_operation_update_one_with_opts()
mongoc_bulk_operation_update_many_with_opts()
mongoc_bulk_operation_replace_one_with_opts()
mongoc_bulk_operation_remove_one_with_opts()
mongoc_bulk_operation_remove_many_with_opts()

The following sections show how to use these methods to specify their corresponding write operations.

Insert Operations

To perform an insert operation, add the insert instructions to the mongoc_bulk_operation_t, which queues the operation as part of the bulk write.

The following example calls the mongoc_bulk_operation_insert_with_opts() function, passing the document to insert and the mongoc_bulk_operation_t value as parameters:

bson_t *insert_doc = BCON_NEW (
    "name", BCON_UTF8 ("Mongo's Deli"),
    "cuisine", BCON_UTF8 ("Sandwiches"),
    "borough", BCON_UTF8 ("Manhattan"),
    "restaurant_id", BCON_UTF8 ("1234")
);
bson_error_t error;
if (!mongoc_bulk_operation_insert_with_opts (bulk, insert_doc, NULL, &error)) {
    fprintf (stderr, "Failed to add insert operation: %s\n", error.message);
}
bson_destroy (insert_doc);

To insert multiple documents, call mongoc_bulk_operation_insert_with_opts() for each document.

Update Operations

To perform an update operation, add the update instructions to the mongoc_bulk_operation_t, which queues the operation as part of the bulk write.

The following example calls the mongoc_bulk_operation_update_one_with_opts() function, passing a query filter, document updates, and the mongoc_bulk_operation_t value as parameters:

bson_t *filter_doc = BCON_NEW ("name", BCON_UTF8 ("Mongo's Deli"));
bson_t *update_doc = BCON_NEW ("$set", "{", "cuisine", BCON_UTF8 ("Sandwiches and Salads"), "}");
bson_error_t error;
if (!mongoc_bulk_operation_update_one_with_opts (bulk, filter_doc, update_doc, NULL, &error)) {
    fprintf (stderr, "Failed to add update operation: %s\n", error.message);
}
bson_destroy (filter_doc);
bson_destroy (update_doc);

To update multiple documents, call mongoc_bulk_operation_update_many_with_opts() and pass in the same parameters. This instructs the driver to update all documents that match your query filter.

The following example queues an update many operation to the bulk write:

bson_t *filter_doc = BCON_NEW ("name", BCON_UTF8 ("Mongo's Deli"));
bson_t *update_doc = BCON_NEW ("$set", "{", "cuisine", BCON_UTF8 ("Sandwiches and Salads"), "}");
bson_error_t error;
if (!mongoc_bulk_operation_update_many_with_opts (bulk, filter_doc, update_doc, NULL, &error)) {
    fprintf (stderr, "Failed to add update operation: %s\n", error.message);
}
bson_destroy (filter_doc);
bson_destroy (update_doc);

Replace Operations

A replace operation removes all fields and values of a specified document and replaces them with new ones. To perform a replace operation, add the replacement instructions to the mongoc_bulk_operation_t, which queues the operation as part of the bulk write.

The following example calls the mongoc_bulk_operation_replace_one_with_opts() function, passing a query filter, replacement document, and the mongoc_bulk_operation_t value as parameters:

bson_t *filter_doc = BCON_NEW ("restaurant_id", BCON_UTF8 ("1234"));
bson_t *replace_doc = BCON_NEW (
    "name", BCON_UTF8 ("Mongo's Deli"),
    "cuisine", BCON_UTF8 ("Sandwiches and Salads"),
    "borough", BCON_UTF8 ("Brooklyn"),
    "restaurant_id", BCON_UTF8 ("5678")
);
bson_error_t error;
if (!mongoc_bulk_operation_replace_one_with_opts (bulk, filter_doc, replace_doc, NULL, &error)) {
    fprintf (stderr, "Failed to add replace operation: %s\n", error.message);
}
bson_destroy (filter_doc);
bson_destroy (replace_doc);

To replace multiple documents, call mongoc_bulk_operation_replace_one_with_opts() for each document.

Delete Operations

To perform a delete operation, add the delete instructions to the mongoc_bulk_operation_t, which queues the operation as part of the bulk write.

The following example calls the mongoc_bulk_operation_remove_one_with_opts() function, passing a query filter and the mongoc_bulk_operation_t value as parameters:

bson_t *filter_doc = BCON_NEW ("restaurant_id", BCON_UTF8 ("5678"));
bson_error_t error;
if (!mongoc_bulk_operation_remove_one_with_opts (bulk, filter_doc, NULL, &error)) {
    fprintf (stderr, "Failed to add delete operation: %s\n", error.message);
}
bson_destroy (filter_doc);

To delete multiple documents, call the mongoc_bulk_operation_remove_many_with_opts() function and pass in the same parameters. This instructs the driver to delete all documents that match your query filter.

The following example queues a delete many operation to the bulk write:

bson_t *filter_doc = BCON_NEW ("borough", BCON_UTF8 ("Manhattan"));
bson_error_t error;
if (!mongoc_bulk_operation_remove_many_with_opts (bulk, filter_doc, NULL, &error)) {
    fprintf (stderr, "Failed to add delete operation: %s\n", error.message);
}
bson_destroy (filter_doc);

Run the Bulk Operation

To run each write operation queued in the bulk write, call the mongoc_bulk_operation_execute() function. This function accepts the following parameters:

mongoc_bulk_operation_t value: Contains the instructions for each write operation
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

The following example performs the insert, update, replace, and delete operations specified in the preceding sections of this guide by calling the mongoc_bulk_operation_execute() function:

bson_error_t error;
bool result = mongoc_bulk_operation_execute (bulk, NULL, &error);
if (!result) {
    printf ("Bulk operation error: %s\n", error.message);
}
mongoc_bulk_operation_destroy (bulk);

If any of the write operations fail, the C driver sets the output error and does not perform any further operations.

Customize Bulk Write Operations

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

Option	Description
`ordered`	If `true`, the driver performs the write operations in the order provided. If an error occurs, the remaining operations are not attempted. If `false`, the driver performs the operations in an arbitrary order and attempts to perform all operations. Defaults to `true`.
`writeConcern`	Specifies the write concern for the bulk operation. For more information, see Write Concern in the MongoDB Server manual.
`sessionId`	Runs the bulk operations within the specified session. For more information, see Server Sessions in the MongoDB Server manual.
`comment`	Attaches a comment to the operation. For more information, see the delete command fields guide in the MongoDB Server manual.
`let`	Specifies a document with a list of values to improve operation readability. Values must be constant or closed expressions that don't reference document fields. For more information, see the let statement in the MongoDB Server manual.

The following example calls the mongoc_collection_create_bulk_operation_with_opts() function and sets the ordered option to false:

bson_t opts;
BSON_APPEND_BOOL (&opts, "ordered", false);
bulk = mongoc_collection_create_bulk_operation_with_opts (collection, &opts);
// Perform bulk operation
bson_destroy (&opts);
mongoc_bulk_operation_destroy (bulk);

If any of the write operations in an unordered bulk write fail, the C driver reports the errors only after attempting all operations.

Note

Unordered bulk operations do not guarantee order of execution. The order can differ from the way you list them to optimize the runtime.

Additional Information

To learn how to perform individual write operations, see the following guides:

API Documentation

To learn more about any of the functions or types discussed in this guide, see the following API documentation:

Back

Delete Documents

Transactions