Bulk Write Operations

Sample Data

The examples in this guide use the sample_restaurants.restaurants and sample_mflix.movies collections 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.

Insert Operations

To perform an insert operation, create an InsertOneModel<TDocument> instance and specify the document you want to insert.

The following example creates an instance of the InsertOneModel<BsonDocument> class. This instance directs the driver to insert a document in which the "name" field is "Mongo's Deli" into the restaurants collection.

var insertOneModel = new InsertOneModel<BsonDocument>(
    new BsonDocument{
        { "name", "Mongo's Deli" },
        { "cuisine", "Sandwiches" },
        { "borough", "Manhattan" },
        { "restaurant_id", "1234" }
    }
);

To insert multiple documents, create an instance of InsertOneModel<TDocument> for each document.

Update Operations

To update a single document, create an instance of UpdateOneModel<TDocument> and pass the following arguments:

• Query filter that specifies the criteria used to match documents in your collection. To learn more about specifying a query, see Query and Projection Operators in the MongoDB Server manual.

• Update document that describes the update to perform. To learn more about specifying an update, see Update Operators in the MongoDB Server manual.

An UpdateOneModel<TDocument> instance specifies an update for the first document that matches your query filter.

In the following code example, the UpdateOneModel<BsonDocument> object represents an update operation on the restaurants collection. The operation matches the first document in the collection where the value of the name field is "Mongo's Deli". It then updates the value of the cuisine field in the matched document to "Sandwiches and Salads".

var updateOneModel = new UpdateOneModel<BsonDocument>(
    Builders<BsonDocument>.Filter.Eq("name", "Mongo's Deli"),
    Builders<BsonDocument>.Update.Set("cuisine", "Sandwiches and Salads")
);

To update multiple documents, create an instance of UpdateManyModel<TDocument> and pass the same arguments as for UpdateOneModel<TDocument>. The UpdateManyModel<TDocument> class specifies updates for all documents that match your query filter.

In the following code example, the UpdateManyModel<BsonDocument> object represents an update operation on the restaurants collection. The operation matches all documents in the collection where the value of the name field is "Mongo's Deli". It then updates the value of the cuisine field to "Sandwiches and Salads".

var updateManyModel = new UpdateManyModel<BsonDocument>(
    Builders<BsonDocument>.Filter.Eq("name", "Mongo's Deli"),
    Builders<BsonDocument>.Update.Set("cuisine", "Sandwiches and Salads")
);

Replace Operations

A replace operation removes all fields and values of a specified document and replaces them with new fields and values that you specify. To perform a replace operation, create an instance of ReplaceOneModel<TDocument> and pass a query filter and the fields and values you want to replace the matching document with.

In the following example, the ReplaceOneModel<BsonDocument> object represents a replace operation on the restaurants collection. The operation matches the document in the collection where the value of the restaurant_id field is "1234". It then removes all fields other than _id from this document, and sets new values in the name, cuisine, borough, and restaurant_id fields.

var replaceOneModel = new ReplaceOneModel<BsonDocument>(
    Builders<BsonDocument>.Filter.Eq("restaurant_id", "1234"),
    new BsonDocument{
        { "name", "Mongo's Pizza" },
        { "cuisine", "Pizza" },
        { "borough", "Brooklyn" },
        { "restaurant_id", "5678" }
    }
);

To replace multiple documents, you must create an instance of ReplaceOneModel<TDocument> for each document.

Delete Operations

To delete a document, create an instance of DeleteOneModel<TDocument> and pass a query filter specifying the document you want to delete. A DeleteOneModel<TDocument> instance provides instructions to delete only the first document that matches your query filter.

In the following code example, the DeleteOneModel<BsonDocument> object represents a delete operation on the restaurants collection. The operation matches and deletes the first document where the value of the restaurant_id field is "5678".

var deleteOneModel = new DeleteOneModel<BsonDocument>(
    Builders<BsonDocument>.Filter.Eq("restaurant_id", "5678")
);

To delete multiple documents, create an instance of DeleteManyModel<TDocument> and pass a query filter specifying the documents you want to delete. An instance of DeleteManyModel<TDocument> provides instructions to remove all documents that match your query filter.

In the following code example, the DeleteManyModel<BsonDocument> object represents a delete operation on the restaurants collection. The operation matches and deletes all documents where the value of the name field is "Mongo's Deli".

var deleteManyModel = new DeleteManyModel<BsonDocument>(
    Builders<BsonDocument>.Filter.Eq("name", "Mongo's Deli")
);

Perform the Bulk Operation

After you define a WriteModel instance for each operation that you want to perform, create an instance of a class that implements the IEnumerable interface. Add your WriteModel objects to this IEnumerable, then pass the IEnumerable to the BulkWrite() or BulkWriteAsync() method. By default, these methods run the operations in the order they're defined in the list.

Select from the following tabs to view how to use the synchronous BulkWrite() method and the asynchronous BulkWriteAsync() method to perform a bulk write operation on the restaurants collection:

var models = new List<WriteModel<BsonDocument>>
{
    new InsertOneModel<BsonDocument>(
        new BsonDocument{
            { "name", "Mongo's Deli" },
            { "cuisine", "Sandwiches" },
            { "borough", "Manhattan" },
            { "restaurant_id", "1234" }
        }
    ),
    new InsertOneModel<BsonDocument>(
        new BsonDocument{
            { "name", "Mongo's Deli" },
            { "cuisine", "Sandwiches" },
            { "borough", "Brooklyn" },
            { "restaurant_id", "5678" }
        }
    ),
    new UpdateManyModel<BsonDocument>(
        Builders<BsonDocument>.Filter.Eq("name", "Mongo's Deli"),
        Builders<BsonDocument>.Update.Set("cuisine", "Sandwiches and Salads")
    ),
    new DeleteOneModel<BsonDocument>(
        Builders<BsonDocument>.Filter.Eq("restaurant_id", "1234")
    )
};
var results = collection.BulkWrite(models);
Console.WriteLine(results);

var models = new List<WriteModel<BsonDocument>>
{
    new InsertOneModel<BsonDocument>(
        new BsonDocument{
            { "name", "Mongo's Deli" },
            { "cuisine", "Sandwiches" },
            { "borough", "Manhattan" },
            { "restaurant_id", "1234" }
        }
    ),
    new InsertOneModel<BsonDocument>(
        new BsonDocument{
            { "name", "Mongo's Deli" },
            { "cuisine", "Sandwiches" },
            { "borough", "Brooklyn" },
            { "restaurant_id", "5678" }
        }
    ),
    new UpdateManyModel<BsonDocument>(
        Builders<BsonDocument>.Filter.Eq("name", "Mongo's Deli"),
        Builders<BsonDocument>.Update.Set("cuisine", "Sandwiches and Salads")
    ),
    new DeleteOneModel<BsonDocument>(
        Builders<BsonDocument>.Filter.Eq("restaurant_id", "1234")
    )
};
var results = await collection.BulkWriteAsync(models);
Console.WriteLine(results);

The preceding code examples produce the following output:

MongoDB.Driver.BulkWriteResult1+Acknowledged[MongoDB.Bson.BsonDocument]

Customize Bulk Write Operation

When you call the BulkWrite() or BulkWriteAsync() method, you can pass an instance of the BulkWriteOptions class. The BulkWriteOptions class contains the following properties, which represent options you can use to configure the bulk write operation:

The following code examples use a BulkWriteOptions object to perform an unordered bulk write operation:

var models = new List<WriteModel<BsonDocument>>
{
new DeleteOneModel<BsonDocument>(
    Builders<BsonDocument>.Filter.Eq("restaurant_id", "5678")
)
};
var options = new BulkWriteOptions
{
    IsOrdered = false,
};
collection.BulkWrite(models, options);

var models = new List<WriteModel<BsonDocument>>
{
new DeleteOneModel<BsonDocument>(
    Builders<BsonDocument>.Filter.Eq("restaurant_id", "5678")
)
};
var options = new BulkWriteOptions
{
    IsOrdered = false,
};
await collection.BulkWriteAsync(models, options);

Return Value

The BulkWrite() and BulkWriteAsync() methods return a BulkWriteResult object that contains the following properties:

Handling Exceptions

If any of the operations in a bulk write operation fail, the .NET/C# Driver throws a BulkWriteError and does not perform any further operations.

A BulkWriteError object contains the Index property that describes the index of the request that resulted in an error.

Insert Operations

To perform an insert operation, create an instance of the BulkWriteInsertOneModel<TDocument> class. The BulkWriteInsertOneModel<TDocument> constructor accepts the following parameters:

The following example creates instances of the BulkWriteInsertOneModel<TDocument> class. These instances direct the driver to insert documents into the sample_restaurants.restaurants and sample_mflix.movies collections.

var restaurantToInsert = new BulkWriteInsertOneModel<BsonDocument>(
    "sample_restaurants.restaurants",
    new BsonDocument{
        { "name", "Mongo's Deli" },
        { "cuisine", "Sandwiches" },
        { "borough", "Manhattan" },
        { "restaurant_id", "1234" }
    }
);
var movieToInsert = new BulkWriteInsertOneModel<BsonDocument>(
    "sample_mflix.movies",
    new BsonDocument{
        { "title", "Silly Days" },
        { "year", 2022 }
    }
);

Update Operations

To update a single document, create an instance of the BulkWriteUpdateOneModel<TDocument> class. The BulkWriteUpdateOneModel<TDocument> constructor accepts the following parameters:

In the following code example, the BulkWriteUpdateOneModel<BsonDocument> objects represent update operations on the sample_restaurants.restaurants and sample_mflix.movies collections.

var restaurantUpdate = new BulkWriteUpdateOneModel<BsonDocument>(
    "sample_restaurants.restaurants",
    Builders<BsonDocument>.Filter.Eq("name", "Mongo's Deli"),
    Builders<BsonDocument>.Update.Set("cuisine", "Sandwiches and Salads")
);
var movieUpdate = new BulkWriteUpdateOneModel<BsonDocument>(
    "sample_mflix.movies",
    Builders<BsonDocument>.Filter.Eq("title", "Carrie"),
    Builders<BsonDocument>.Update.Set("seen", True)
);

To update multiple documents, create an instance of the BulkWriteUpdateManyModel<TDocument> class. The constructor for this class accepts the same parameters as the BulkWriteUpdateOneModel<TDocument> constructor. The BulkWriteUpdateManyModel<TDocument> operation updates all documents that match your query filter.

In the following code example, the BulkWriteUpdateManyModel<BsonDocument> object represents an update operation on the sample_restaurants.restaurants collection. The operation matches all documents in the collection where the value of the name field is "Starbucks". It then updates the value of the cuisine field to "Coffee (Chain)".

var updateManyModel = new BulkWriteUpdateManyModel<BsonDocument>(
    "sample_restaurants.restaurants",
    Builders<BsonDocument>.Filter.Eq("name", "Starbucks"),
    Builders<BsonDocument>.Update.Set("cuisine", "Coffee (Chain)")
);

Replace Operations

To replace the fields in a document, create an instance of the BulkWriteReplaceOneModel<TDocument> class. The BulkWriteReplaceOneModel<TDocument> constructor accepts the following parameters:

In the following example, the BulkWriteReplaceOneModel<BsonDocument> objects represent replace operations on the sample_restaurants.restaurants and sample_mflix.movies collections.

var restaurantReplacement = new BulkWriteReplaceOneModel<BsonDocument>(
    "sample_restaurants.restaurants",
    Builders<BsonDocument>.Filter.Eq("restaurant_id", "1234"),
    new BsonDocument{
        { "name", "Mongo's Pizza" },
        { "cuisine", "Pizza" },
        { "borough", "Brooklyn" },
        { "restaurant_id", "5678" }
    }
);
var movieReplacement = new BulkWriteReplaceOneModel<BsonDocument>(
    "sample_mflix.movies",
    Builders<BsonDocument>.Filter.Eq("title", "Insomnia"),
    new BsonDocument{
        { "name", "Loving Sylvie" },
        { "year", 1999 }
    }
);

Delete Operations

To delete a document, create an instance of the BulkWriteDeleteOneModel<TDocument> class. The BulkWriteDeleteOneModel<TDocument> constructor accepts the following parameters:

In the following code example, the BulkWriteDeleteOneModel<BsonDocument> objects represent delete operations on the sample_restaurants.restaurants and sample_mflix.movies collections.

var restaurantToDelete = new BulkWriteDeleteOneModel<BsonDocument>(
    "sample_restaurants.restaurants",
    Builders<BsonDocument>.Filter.Eq("restaurant_id", "5678")
);
var movieToDelete = new BulkWriteDeleteOneModel<BsonDocument>(
    "sample_mflix.movies",
    Builders<BsonDocument>.Filter.Eq("title", "Mr. Nobody")
);

To delete multiple documents, create an instance of the BulkWriteDeleteManyModel<TDocument> class and pass a query filter that specifies the document that you want to delete. The DeleteMany operation removes all documents that match your query filter.

In the following code example, the BulkWriteDeleteManyModel<BsonDocument> object represents a delete operation on the sample_restaurants.restaurants collection. The operation matches and deletes all documents where the value of the name field is "Mongo's Deli".

var deleteManyModel = new BulkWriteDeleteManyModel<BsonDocument>(
    "sample_restaurants.restaurants",
    Builders<BsonDocument>.Filter.Eq("name", "Mongo's Deli")
);

Perform the Bulk Operation

After you define a BulkWriteModel instance for each operation that you want to perform, create an instance of a class that implements the IReadOnlyList interface. Add your BulkWriteModel objects to this IReadOnlyList, then pass the IReadOnlyList to the BulkWrite() or BulkWriteAsync() method. By default, these methods run the operations in the order they're defined in the collection.

Select from the following tabs to view how to use the synchronous BulkWrite() method and the asynchronous BulkWriteAsync() method to perform a bulk write operation on multiple namespaces.

var client = new MongoClient("mongodb://localhost:27017");
var restaurantNamespace = "sample_restaurants.restaurants";
var movieNamespace = "sample_mflix.movies";
var bulkWriteModels = new[]
{
    new BulkWriteInsertOneModel<BsonDocument>(
        restaurantNamespace,
        new BsonDocument{
            { "name", "Mongo's Deli" },
            { "cuisine", "Sandwiches" },
            { "borough", "Manhattan" },
            { "restaurant_id", "1234" }
        }
    ),
    new BulkWriteInsertOneModel<BsonDocument>(
        movieNamespace,
        new BsonDocument{
            { "name", "Sarah's Secret" },
            { "year", 1988 }
        }
    ),
    new BulkWriteUpdateManyModel<BsonDocument>(
        restaurantNamespace,
        Builders<BsonDocument>.Filter.Eq("name", "Mongo's Deli"),
        Builders<BsonDocument>.Update.Set("cuisine", "Sandwiches and Salads")
    ),
    new BulkWriteDeleteOneModel<BsonDocument>(
        movieNamespace,
        Builders<BsonDocument>.Filter.Eq("title", "House")
    )
};
var result = client.BulkWrite(bulkWriteModels);
Console.WriteLine(result);

var client = new MongoClient("mongodb://localhost:27017");
var restaurantNamespace = "sample_restaurants.restaurants";
var movieNamespace = "sample_mflix.movies";
var bulkWriteModels = new[]
{
    new BulkWriteInsertOneModel<BsonDocument>(
        restaurantNamespace,
        new BsonDocument{
            { "name", "Mongo's Deli" },
            { "cuisine", "Sandwiches" },
            { "borough", "Manhattan" },
            { "restaurant_id", "1234" }
        }
    ),
    new BulkWriteInsertOneModel<BsonDocument>(
        movieNamespace,
        new BsonDocument{
            { "name", "Sarah's Secret" },
            { "year", 1988 }
        }
    ),
    new BulkWriteUpdateManyModel<BsonDocument>(
        restaurantNamespace,
        Builders<BsonDocument>.Filter.Eq("name", "Mongo's Deli"),
        Builders<BsonDocument>.Update.Set("cuisine", "Sandwiches and Salads")
    ),
    new BulkWriteDeleteOneModel<BsonDocument>(
        movieNamespace,
        Builders<BsonDocument>.Filter.Eq("title", "House")
    )
};
var result = await client.BulkWriteAsync(bulkWriteModels);
Console.WriteLine(result);

The preceding code examples produce the following output:

BulkWriteResult({'writeErrors': [], 'writeConcernErrors': [], 'nInserted': 2, 'nUpserted': 0, 'nMatched': 2, 'nModified': 2, 'nRemoved': 1, 'upserted': []}, acknowledged=True)

Customize Bulk Write

When you call the BulkWrite() or BulkWriteAsync() method, you can pass an instance of the ClientBulkWriteOptions class. The ClientBulkWriteOptions class contains the following properties, which represent options you can use to configure the bulk write operation:

The following code examples use a ClientBulkWriteOptions object to customize the bulk write operation:

var client = new MongoClient("mongodb://localhost:27017");
var deleteOneModel = new BulkWriteDeleteOneModel<BsonDocument>(
    "sample_restaurants.restaurants",
    Builders<BsonDocument>.Filter.Eq("restaurant_id", "5678")
);
var clientBulkWriteOptions = new ClientBulkWriteOptions
{
    IsOrdered = false,
    WriteConcern = WriteConcern.Unacknowledged,
    VerboseResult = true
};
var result = client.BulkWrite(deleteOneModel, clientBulkWriteOptions);

var client = new MongoClient("mongodb://localhost:27017");
var deleteOneModel = new BulkWriteDeleteOneModel<BsonDocument>(
    "sample_restaurants.restaurants",
    Builders<BsonDocument>.Filter.Eq("restaurant_id", "5678")
);
var clientBulkWriteOptions = new ClientBulkWriteOptions
{
    IsOrdered = false,
    WriteConcern = WriteConcern.Unacknowledged,
    VerboseResult = true
};
var result = await client.BulkWriteAsync(deleteOneModel, clientBulkWriteOptions);

Return Value

The BulkWrite() and BulkWriteAsync() methods return a ClientBulkWriteResult object that contains the following properties:

Handling Exceptions

If any of the operations in a bulk write operation fail, the .NET/C# Driver throws a ClientBulkWriteException and does not perform any further operations.

A ClientBulkWriteException object contains the following properties:

API Documentation

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

• Collection Bulk Write

  • BulkWrite()

  • BulkWriteAsync()

  • BulkWriteOptions

  • BulkWriteResult

  • InsertOneModel

  • UpdateOneModel

  • UpdateManyModel

  • ReplaceOneModel

  • DeleteOneModel

  • DeleteManyModel

  • BulkWriteError

• Client Bulk Write

  • BulkWrite()

  • BulkWriteAsync()

  • ClientBulkWriteOptions

  • ClientBulkWriteResult

  • BulkWriteInsertOneModel

  • BulkWriteUpdateOneModel

  • BulkWriteUpdateManyModel

  • BulkWriteReplaceOneModel

  • BulkWriteDeleteOneModel

  • BulkWriteDeleteManyModel

  • BulkWriteInsertOneResult

  • BulkWriteUpdateResult

  • BulkWriteDeleteResult

  • ClientBulkWriteException