Docs Menu

Docs Home → Go

Insert a Document

On this page

  • Overview
  • The _id Field
  • Insert a Document
  • Example
  • Modify InsertOne Behavior
  • Insert Multiple Documents
  • Example
  • Modify InsertMany Behavior
  • Ordered Behavior
  • Additional Information
  • API Documentation

Overview

In this guide, you can learn how to insert documents into a MongoDB collection.

Before you can find, update, and delete documents in MongoDB, you need to insert those documents. You can insert one document using the InsertOne() method, or insert multiple documents using either the InsertMany() or BulkWrite() method.

The following sections focus on InsertOne() and InsertMany(). To learn how to use the BulkWrite() method, see the Bulk Operations guide.

The _id Field

In MongoDB, each document must contain a unique _id field.

The two options for managing this field are:

  • Managing this field yourself, ensuring that each value you use is unique.

  • Letting the driver automatically generate unique ObjectId values. The driver generates unique ObjectId values for documents that you do not explicitly specify an _id.

Unless you provide strong guarantees for uniqueness, MongoDB recommends you let the driver automatically generate _id values.

Note

Duplicate _id values violate unique index constraints, which causes the driver to return a WriteError.

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 a Document

Use the InsertOne() method to insert a single document into a collection.

Upon successful insertion, the method returns an InsertOneResult instance that contains the _id of the new document.

Example

This example uses the following Book struct as a model for documents in the books collection:

type Book struct {
	Title  string
	Author string
}

The following example creates and inserts a document into the books collection using the InsertOne() method:

coll := client.Database("db").Collection("books")
doc := Book{Title: "Atonement", Author: "Ian McEwan"}
result, err := coll.InsertOne(context.TODO(), doc)
fmt.Printf("Inserted document with _id: %v\n", result.InsertedID)

Modify InsertOne Behavior

You can modify the behavior of InsertOne() by constructing and passing an optional InsertOneOptions struct. The available options to set with InsertOneOptions are:

Option
Description
BypassDocumentValidation
If true, allows the write to opt-out of document level validation.
Default: false

Construct an InsertOneOptions as follows:

opts := options.InsertOne().SetBypassDocumentValidation(true)

Insert Multiple Documents

Use the InsertMany() method to insert multiple documents into a collection.

Upon successful insertion, the InsertMany() method returns an InsertManyResult instance that contains the _id fields of the inserted documents.

Example

The following example creates and inserts multiple documents into the books collection using the InsertMany() method:

coll := client.Database("myDB").Collection("favorite_books")
docs := []interface{}{
    Book{Title: "Cat's Cradle", Author: "Kurt Vonnegut Jr."},
    Book{Title: "In Memory of Memory", Author: "Maria Stepanova"},
    Book{Title: "Pride and Prejudice", Author: "Jane Austen"},
}
result, err := coll.InsertMany(context.TODO(), docs)
fmt.Printf("Documents inserted: %v\n", len(result.InsertedIDs))
for _, id := range result.InsertedIDs {
    fmt.Printf("Inserted document with _id: %v\n", id)
}

Your output should look like this:

Documents inserted: 3
Inserted document with _id: ObjectID("...")
Inserted document with _id: ObjectID("...")
Inserted document with _id: ObjectID("...")

Modify InsertMany Behavior

You can modify the behavior of InsertMany() by constructing and passing an optional InsertManyOptions struct. The available options to set with InsertManyOptions are:

Option
Description
BypassDocumentValidation
If true, allows the write to opt-out of document level validation.
Default: false
Ordered
If true, the driver sends documents to the server in the order provided. If an error occurs, the driver and server abort all remaining insert operations. To learn more, see Ordered Behavior.
Default: false

Construct an InsertManyOptions as follows:

opts := options.InsertMany().SetBypassDocumentValidation(true).SetOrdered(false)

Ordered Behavior

Assume you want to insert the following documents:

{ "_id": 1, "title": "Where the Wild Things Are" }
{ "_id": 2, "title": "The Very Hungry Caterpillar" }
{ "_id": 1, "title": "Blueberries for Sal" }
{ "_id": 3, "title": "Goodnight Moon" }

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

Note

You can get an acknowledgement of successful document insertion even if a BulkWriteException occurs:

type Book struct {
    ID    int `bson:"_id"`
    Title string
}
...
docs := []interface{}{
    Book{ID: 1, Title: "Where the Wild Things Are"},
    Book{ID: 2, Title: "The Very Hungry Caterpillar"},
    Book{ID: 1, Title: "Blueberries for Sal"},
    Book{ID: 3, Title: "Goodnight Moon"},
}
result, err := coll.InsertMany(context.TODO(), docs)
if err != nil {
    fmt.Printf("A bulk write error occurred, but %v documents were still inserted.\n", len(result.InsertedIDs))
}
for _, id := range result.InsertedIDs {
    fmt.Printf("Inserted document with _id: %v\n", id)
}

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

{ "_id": 1, "title": "Where the Wild Things Are" }
{ "_id": 2, "title": "The Very Hungry Caterpillar" }

Additional Information

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

To learn more about performing the operations mentioned, see the following guides:

API Documentation

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

←  Write OperationsDelete Documents →

On this page