Insert Operations

On this page

Overview

Insert a Single Document
Insert Multiple Documents
Insert Example: Full File
Additional Information

Overview

In this guide, you can learn how to insert documents with the MongoDB Java driver.

You can use MongoDB to retrieve, update, and delete information. To perform any of those operations, that information, such as user profiles and orders, needs to exist in MongoDB. For that information to exist, first perform an insert operation.

An insert operation inserts a single or multiple documents into MongoDB using the insertOne(), insertMany(), and bulkWrite() methods.

The following sections focus on insertOne() and insertMany(). For information on how to use the bulkWrite() method, see our guide on Bulk Operations.

Note

The id_ Field in Insert Operations

When inserting a document, MongoDB enforces one constraint on your documents by default: each document must contain a unique _id value. Duplicate _id values violate unique index constraints, resulting in a WriteError.

There are two ways to manage this field:

You can manage this field yourself, ensuring each value you use is unique.
You can let the driver automatically generate unique ObjectId values.

Unless you have provided strong guarantees for uniqueness, we recommend you let the driver automatically generate _id values.

For more information about unique indexes, see the manual entry on Unique Indexes.

Insert a Single Document

Use the insertOne() method when you want to insert a single document.

On successful insertion, the method returns an InsertOneResult instance representing the _id of the new document.

Example

The following example creates and inserts a document using the insertOne() method:

Document doc1 = new Document("color", "red").append("qty", 5);
InsertOneResult result = collection.insertOne(doc1);
System.out.println("Inserted a document with the following id: " 
    + result.getInsertedId().asObjectId().getValue());

The output of the preceding code resembles the following:

Inserted a document with the following id: 60930c39a982931c20ef6cd6

For more information about the methods and classes mentioned in this section, see the following resources:

insertOne() API Documentation
InsertOneResult API Documentation
Manual Explanation on insertOne()
Runnable Insert a Document Example

Insert Multiple Documents

Use the insertMany() method when you want to insert multiple documents. This method inserts documents in the order specified until an exception occurs, if any.

For example, assume you want to insert the following documents:

{ "_id": 3, "color": "red", "qty": 5 }
{ "_id": 4, "color": "purple", "qty": 10 }
{ "_id": 3, "color": "yellow", "qty": 3 }
{ "_id": 6, "color": "blue", "qty": 8 }

If you attempt to insert these documents, a WriteError occurs at the third document and the documents prior to the error get inserted into your collection.

Tip

Use a try-catch block to get an acknowledgment for successfully processed documents before the error occurs:

List<Integer> insertedIds = new ArrayList<>();
// Inserts sample documents and prints their "_id" values
try {
    InsertManyResult result = collection.insertMany(documents);  
    result.getInsertedIds().values()
        .forEach(doc -> insertedIds.add(doc.asInt32().getValue()));
    System.out.println("Inserted documents with the following ids: " + insertedIds);
// Prints a message if any exceptions occur during the operation and the "_id" values of inserted documents
} catch(MongoBulkWriteException exception) {
    exception.getWriteResult().getInserts()
        .forEach(doc -> insertedIds.add(doc.getId().asInt32().getValue()));
    System.out.println("A MongoBulkWriteException occurred, but there are " + 
        "successfully processed documents with the following ids: " + insertedIds);
}

The output consists of documents MongoDB can process and should look something like this:

A MongoBulkWriteException occurred, but there are successfully processed
documents with the following ids: [3, 4, 6]

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

{ "_id": 3, "color": "red", "qty": 5 }
{ "_id": 4, "color": "purple", "qty": 10 }

On successful insertion, the method returns an InsertManyResult instance representing the _id of each new document.

Example

The following example creates and adds two documents to a List, and inserts the List using the insertMany() method:

List<Document> documents = new ArrayList<>();
Document doc1 = new Document("color", "red").append("qty", 5);
Document doc2 = new Document("color", "purple").append("qty", 10);
documents.add(doc1);
documents.add(doc2);
InsertManyResult result = collection.insertMany(documents);
// Retrieves and prints the ID values of each inserted document
List<ObjectId> insertedIds = new ArrayList<>();
result.getInsertedIds().values()
    .forEach(doc -> insertedIds.add(doc.asObjectId().getValue()));
System.out.println("Inserted documents with the following ids: " + insertedIds);

The output of the preceding code resembles the following:

Inserted documents with the following ids: [60930c3aa982931c20ef6cd7,
60930c3aa982931c20ef6cd8]

Insert Example: Full File

Note

Example Setup

This example connects to an instance of MongoDB by using a connection URI. To learn more about connecting to your MongoDB instance, see the connection guide. This example also uses the movies collection in the sample_mflix database included in the Atlas sample datasets. You can load them into your database on the free tier of MongoDB Atlas by following the Get Started with Atlas Guide.

The following code is a complete, standalone file that performs an insert one operation and an insert many operation:

// Inserts a sample document describing a movie by using the Java driver
package org.example;
import java.util.Arrays;
import org.bson.Document;
import org.bson.types.ObjectId;
import com.mongodb.MongoException;
import com.mongodb.client.MongoClient;
import com.mongodb.client.MongoClients;
import com.mongodb.client.MongoCollection;
import com.mongodb.client.MongoDatabase;
import com.mongodb.client.result.InsertOneResult;
import com.mongodb.client.result.InsertManyResult;
import java.util.List;
public class Insert {
    public static void main(String[] args) {
        // Replace the uri string with your MongoDB deployment's connection string
        String uri = "<connection string uri>";
        try (MongoClient mongoClient = MongoClients.create(uri)) {
            MongoDatabase database = mongoClient.getDatabase("sample_mflix");
            MongoCollection<Document> collection = database.getCollection("movies");
            // Inserts a sample document describing a movie into the collection
            InsertOneResult result = collection.insertOne(new Document()
                    .append("_id", new ObjectId())
                    .append("title", "Ski Bloopers")
                    .append("genres", Arrays.asList("Documentary", "Comedy")));
            // Prints the ID of the inserted document
            System.out.println("Inserted document id - insert one: " + result.getInsertedId());
            // Creates two sample documents containing a "title" field
            List<Document> movieList = Arrays.asList(
                    new Document().append("title", "Short Circuit 3"),
                    new Document().append("title", "The Lego Frozen Movie"));
            // Inserts sample documents describing movies into the collection
            InsertManyResult result = collection.insertMany(movieList);
            // Prints the IDs of the inserted documents
            System.out.println("Inserted document id - insert many: " + result.getInsertedIds());
        }
    }
}

insertOne() document id: BsonObjectId{value=...}
insertMany() document ids: {0=BsonObjectId{value=...}, 1=BsonObjectId{value=...}}

Additional Information

API Documentation

For more information about the methods and classes used to insert documents, see the following API documentation:

Server Manual Entries

Back

CRUD Operations

Query Documents