Insert Documents

Open Interactive Tutorial

Overview

In this guide, you can learn how to use the MongoDB .NET/C# Driver to add documents to a MongoDB collection by performing insert operations.

An insert operation inserts one or more documents into a MongoDB collection. The .NET/C# Driver provides the following methods to perform insert operations, each of which has an asynchronous and synchronous version:

• InsertOneAsync() or InsertOne()

• InsertManyAsync() or InsertMany()

public class Restaurant
{
    public ObjectId Id { get; set; }
    public string Name { get; set; }
    [BsonElement("restaurant_id")]
    public string RestaurantId { get; set; }
    public string Cuisine { get; set; }
    public Address Address { get; set; }
    public string Borough { get; set; }
    public List<GradeEntry> Grades { get; set; }
}

public class Address
{
    public string Building { get; set; }
    [BsonElement("coord")]
    public double[] Coordinates { get; set; }
    public string Street { get; set; }
    [BsonElement("zipcode")]
    public string ZipCode { get; set; }
}

public class GradeEntry
{
    public DateTime Date { get; set; }
    public string Grade { get; set; }
    public float? Score { get; set; }
}

The _id Field

In a MongoDB collection, each document must contain an _id field with a unique field value.

MongoDB allows you to manage this field in two ways:

• You can set this field for each document yourself, ensuring each _id field value is unique.

• You can let the driver automatically generate unique ObjectId values for each document _id. If you do not manually set an _id field value for a document, the driver will populate the field with an ObjectId.

Unless you can guarantee uniqueness, MongoDB recommends you let the driver automatically generate _id values.

To learn more about the _id field, see the Server Manual Entry on Unique Indexes.

To learn more about document structure and rules, see the Server Manual Entry on Documents.

Insert One Document

The following code shows how to use the asynchronous InsertOneAsync() method or the synchronous InsertOne() method to insert one document.

Insert Multiple Documents

The following code shows how to use the asynchronous InsertManyAsync() method or the synchronous InsertMany() method to insert multiple documents.

Modify Insert Behavior

The InsertOne() method takes the document you seek to insert as a parameter. The InsertMany() method takes an IEnumerable collection of documents, such as a list or array, as a parameter.

The InsertOne() method optionally takes a InsertOneOptions type as an additional parameter, which represents options you can use to configure the insert operation. If you don't specify any InsertOneOptions properties, the driver does not customize the insert.

The InsertOneOptions type allows you to configure options with the following properties:

The InsertMany() method optionally takes a InsertManyOptions type as an additional parameter, which has the preceding BypassDocumentValidation and Comment properties and the additional IsOrdered property:

// Generates 5 new restaurants by using a helper method
var restaurants = GenerateDocuments();
// Creates an option object to bypass documentation validation on the documents
var options = new InsertManyOptions() { BypassDocumentValidation = true };
// Inserts the new documents into the restaurants collection with the specified options
_restaurantsCollection.InsertMany(restaurants, options);

Specify Ordered Behavior

Assume you want to insert the following documents:

{ "_id" : 1, "name" : "Restaurant A" }
{ "_id" : 2, "name" : "Restaurant B" }
{ "_id" : 1, "name" : "Restaurant C" }
{ "_id" : 3, "name" : "Restaurant D" }

If you attempt to insert these documents with default InsertManyOptions, the driver throws a MongoBulkWriteException at the third document because of the repeated _id value, but the documents before the error-producing document are still inserted into your collection.

If you look inside your collection, you should be able to see the following documents:

{ "_id" : 1, "name" : "Restaurant A" }
{ "_id" : 2, "name" : "Restaurant B" }

If you set IsOrdered to false in your insert operation, the driver will continue to insert your documents even if some documents produce errors. With this modified insert behavior, the driver throws an exception but inserts all documents that do not produce errors.

If you look inside your collection, you should be able to see the following documents:

{ "_id" : 1, "name" : "Restaurant A" }
{ "_id" : 2, "name" : "Restaurant B" }
{ "_id" : 3, "name" : "Restaurant D" }

Additional Information

For runnable examples of the insert operations, see the following usage examples:

• Insert a Document

• Insert Multiple Documents