Bulk Operations

Overview

In this guide, you can learn how to use the Rust driver to perform bulk operations.

Bulk operations perform multiple write operations against one or more namespaces. A namespace is a combination of the database name and the collection name, in the format <database>.<collection>. Since you perform bulk operations on a Client instance, you can perform bulk operations against any namespace in the cluster accessed by your client.

You can perform bulk operations to reduce the number of calls to the server. Instead of sending a request for each operation, bulk operations perform multiple operations within one action.

This guide includes the following sections:

• Sample Data presents the sample data that is used by the bulk operation examples

• Bulk Operation Types describes how to use WriteModel types to perform bulk insert, replace, update, and delete operations

• Return Type describes the return value of the bulk_write() method and how to access information about the bulk operation

• Modify Behavior describes how to modify the default behavior of the bulk_write() method

• Write to Mixed Namespaces describes how to perform a bulk operation on multiple namespaces in one method call

• Additional Information provides links to resources and API documentation for types and methods mentioned in this guide

Sample Data

The examples in this guide use the following sample documents, which are stored in the mushrooms collection in the db database:

let docs = vec![
    doc! {"name" : "portobello", "color" : "brown", "edible" : true },
    doc! {"name" : "chanterelle", "color" : "yellow", "edible" : true },
    doc! {"name" : "oyster", "color" : "white", "edible" : true },
    doc! {"name" : "fly agaric", "color" : "red", "edible" : false },
];

You can also use custom struct types to represent your sample data. For an example that performs a bulk operation by using Mushroom structs to model the same data, see the Insert Structs Example on this page.

Bulk Operation Types

To perform a bulk write operation, pass an array of WriteModel enum instances to the bulk_write() method.

In this section, you can learn how to perform the following bulk write operations by defining their corresponding WriteModel types:

• Bulk insert operations

• Bulk replace operations

• Bulk update operations

• Bulk delete operations

let mushrooms: Collection<Document> = client.database("db").collection("mushrooms");
let models = vec![
    InsertOneModel::builder()
        .namespace(mushrooms.namespace())
        .document(doc! {
            "name": "lion's mane",
            "color": "white",
            "edible": true
        })
        .build(),
    InsertOneModel::builder()
        .namespace(mushrooms.namespace())
        .document(doc! {
            "name": "angel wing",
            "color": "white",
            "edible": false
        })
        .build(),
];
let result = client.bulk_write(models).await?;
println!("Inserted documents: {}", result.inserted_count);

Inserted documents: 2

#[derive(Serialize)]
struct Mushroom {
    name: String,
    color: String,
    edible: bool,
}

let mushrooms: Collection<Mushroom> = client.database("db").collection("mushrooms");
let lions_mane = Mushroom {
    name: "lion's mane".to_string(),
    color: "white".to_string(),
    edible: true,
};
let angel_wing = Mushroom {
    name: "angel wing".to_string(),
    color: "white".to_string(),
    edible: false,
};
let lions_mane_model = mushrooms.insert_one_model(lions_mane)?;
let angel_wing_model = mushrooms.insert_one_model(angel_wing)?;
let result = client.bulk_write([lions_mane_model, angel_wing_model]).await?;
println!("Inserted documents: {}", result.inserted_count);

Inserted documents: 2

let mushrooms: Collection<Document> = client.database("db").collection("mushrooms");
let models = vec![
    ReplaceOneModel::builder()
        .namespace(mushrooms.namespace())
        .filter(doc! { "name": "portobello" })
        .replacement(doc! {
            "name": "cremini",
            "color": "brown",
            "edible": true
        })
        .build(),
    ReplaceOneModel::builder()
        .namespace(mushrooms.namespace())
        .filter(doc! { "name": "oyster" })
        .replacement(doc! {
            "name": "golden oyster",
            "color": "yellow",
            "edible": true
        })
        .upsert(true)
        .build(),
];
let result = client.bulk_write(models).await?;
println!("Modified documents: {}", result.modified_count);

Modified documents: 2

let mushrooms: Collection<Document> = client.database("db").collection("mushrooms");
let models = vec![
    WriteModel::UpdateOne(
        UpdateOneModel::builder()
            .namespace(mushrooms.namespace())
            .filter(doc! { "name": "fly agaric" })
            .update(doc! { "$set": { "name": "fly amanita" } })
            .upsert(true)
            .build(),
    ),
    WriteModel::UpdateMany(
        UpdateManyModel::builder()
            .namespace(mushrooms.namespace())
            .filter(doc! { "color": "yellow" })
            .update(doc! { "$set": { "color": "yellow/orange" } })
            .build(),
    ),
];
let result = client.bulk_write(models).await?;
println!("Modified documents: {}", result.modified_count);

Modified documents: 2

let mushrooms: Collection<Document> = client.database("db").collection("mushrooms");
let models = vec![
    WriteModel::DeleteOne(
        DeleteOneModel::builder()
            .namespace(mushrooms.namespace())
            .filter(doc! { "color": "red" })
            .build(),
    ),
    WriteModel::DeleteMany(
        DeleteManyModel::builder()
            .namespace(mushrooms.namespace())
            .filter(doc! { "edible": true })
            .build(),
    ),
];
let result = client.bulk_write(models).await?;
println!("Deleted documents: {}", result.deleted_count);

Deleted documents: 4

Return Type

The bulk_write() method returns a SummaryBulkWriteResult struct instance from which you can access information about your bulk operation.

The SummaryBulkWriteResult type has the following fields:

• inserted_count: the number of inserted documents

• matched_count: the number of matched documents

• modified_count: the number of updated documents

• upserted_count: the number of upserted documents

• deleted_count: the number of deleted documents

You can also use the verbose_results() method to see detailed information about each operation. The verbose_results() method returns a VerboseBulkWriteResult struct instance, which has the following fields:

• delete_results: the results of each successful delete operation

• insert_results: the results of each successful insert operation

• update_results: the results of each successful update operation

• summary: a summary of the results of each operation type

The following example chains the verbose_results() method to the bulk_write() method and prints the results of the update and delete operations:

let models = vec![
    WriteModel::DeleteOne(
        DeleteOneModel::builder()
            .namespace(mushrooms.namespace())
            .filter(doc! { "name": "oyster" })
            .build(),
    ),
    WriteModel::UpdateOne(
        UpdateOneModel::builder()
            .namespace(mushrooms.namespace())
            .filter(doc! { "name": "chanterelle" })
            .update(doc! { "$set": { "season": ["July", "August", "September"] } })
            .build(),
    ),
];
let result = client.bulk_write(models).verbose_results().await?;
println!(
    "Update results: {:?}\nDelete results: {:?}\n",
    result.update_results, result.delete_results
);

Update results: {1: UpdateResult { matched_count: 1, modified_count: 1, upserted_id: None }}
Delete results: {0: DeleteResult { deleted_count: 1 }}

Modify Behavior

You can modify the behavior of the bulk_write() method by setting BulkWriteOptions field values. To set these struct fields, chain the fields' corresponding methods to the bulk_write() method.

The BulkWriteOptions struct contains the following fields:

let mushrooms: Collection<Document> = client.database("db").collection("mushrooms");
let models = vec![
    WriteModel::UpdateOne(UpdateOneModel::builder()
        .namespace(mushrooms.namespace())
        .filter(doc! { "name": "portobello" })
        .update(doc! { "$set": { "_id": 123 } })
        .upsert(true)
        .build()),
    WriteModel::InsertOne(InsertOneModel::builder()
        .namespace(mushrooms.namespace())
        .document(doc! {
            "name": "reishi",
            "color": "red/brown",
            "edible": true
        })
        .build()),
];
let result = client.bulk_write(models).ordered(false).await?;
println!(
    "Inserted documents: {}\nDeleted documents: {}",
    result.inserted_count, result.deleted_count
);

Error: Error { kind: BulkWrite(BulkWriteError { write_concern_errors: [], write_errors:
{0: WriteError { code: 66, code_name: None, message: "Plan executor error during update ::
caused by :: Performing an update on the path '_id' would modify the immutable field '_id'",
details: None }}, partial_result: Some(Summary(SummaryBulkWriteResult { inserted_count: 1,
matched_count: 0, modified_count: 0, upserted_count: 0, deleted_count: 0 })) }),
labels: ... }

Write to Mixed Namespaces

The preceding examples on this page perform bulk operations on the db.mushrooms namespace. However, you can perform bulk writes on multiple namespaces in a single method call.

The following example inserts one document into the ingredients.sweet namespace and one document into the meals.dessert namespace:

let sweet: Collection<Document> = client
    .database("ingredients")
    .collection("sweet");
let dessert: Collection<Document> = client
    .database("meals")
    .collection("dessert");
let models = vec![
    InsertOneModel::builder()
        .namespace(sweet.namespace())
        .document(doc! { "name": "brown sugar", "price": 3.99 })
        .build(),
    InsertOneModel::builder()
        .namespace(dessert.namespace())
        .document(doc! { "name": "banana bread", "cook_time": 75 })
        .build(),
];
let result = client.bulk_write(models).await?;
println!("Inserted documents: {}", result.inserted_count);

Inserted documents: 2

Additional Information

To learn more about bulk operations, see Bulk Write Operations in the Server manual.