Navigation
This version of the documentation is archived and no longer supported.

Insert Documents

This page provides examples of insert operations in MongoDB.

Creating a Collection

If the collection does not currently exist, insert operations will create the collection.

Insert a Single Document

New in version 3.2.

  • Other

db.collection.insertOne() inserts a single document into a collection.

The following example inserts a new document into the inventory collection. If the document does not specify an _id field, MongoDB adds the _id field with an ObjectId value to the new document. See Insert Behavior.

pymongo.collection.Collection.insert_one() inserts a single document into a collection.

The following example inserts a new document into the inventory collection. If the document does not specify an _id field, the PyMongo driver adds the _id field with an ObjectId value to the new document. See Insert Behavior.

com.mongodb.client.MongoCollection.insertOne inserts a single document into a collection.

The following example inserts a new document into the inventory collection. If the document does not specify an _id field, the driver adds the _id field with an ObjectId value to the new document. See Insert Behavior.

Collection.insertOne() inserts a single document into a collection.

The following example inserts a new document into the inventory collection. If the document does not specify an _id field, the Node.js driver adds the _id field with an ObjectId value to the new document. See Insert Behavior.

MongoDB\Collection::insertOne() inserts a single document into a collection.

The following example inserts a new document into the inventory collection. If the document does not specify an _id field, the PHP driver adds the _id field with an ObjectId value to the new document. See Insert Behavior.

com.mongodb.reactivestreams.client.MongoCollection.insertOne inserts a single document into a collection with the Java Reactive Streams Driver:

copy 
{ item: "canvas", qty: 100, tags: ["cotton"], size: { h: 28, w: 35.5, uom: "cm" } }

The following example inserts the document above into the inventory collection. If the document does not specify an _id field, the driver adds the _id field with an ObjectId value to the new document. See Insert Behavior.

IMongoCollection.InsertOne() inserts a single document into a collection.

The following example inserts a new document into the inventory collection. If the document does not specify an _id field, the C# driver adds the _id field with an ObjectId value to the new document. See Insert Behavior.

MongoDB::Collection::insert_one() inserts a single document into a collection.

The following example inserts a new document into the inventory collection. If the document does not specify an _id field, the Perl driver adds the _id field with an ObjectId value to the new document. See Insert Behavior.

Mongo::Collection#insert_one() inserts a single document into a collection.

The following example inserts a new document into the inventory collection. If the document does not specify an _id field, the Ruby driver adds the _id field with an ObjectId value to the new document. See Insert Behavior.

collection.insertOne() inserts a single document into a collection.

The following example inserts a new document into the inventory collection. If the document does not specify an _id field, the Scala driver adds the _id field with an ObjectId value to the new document. See Insert Behavior.

  • Other
copy 
db.inventory.insertOne(
   { item: "canvas", qty: 100, tags: ["cotton"], size: { h: 28, w: 35.5, uom: "cm" } }
)

You can run the operation in the web shell below:

copy 
db.inventory.insert_one(
    {"item": "canvas",
     "qty": 100,
     "tags": ["cotton"],
     "size": {"h": 28, "w": 35.5, "uom": "cm"}})
copy 
Document canvas = new Document("item", "canvas")
        .append("qty", 100)
        .append("tags", singletonList("cotton"));

Document size = new Document("h", 28)
        .append("w", 35.5)
        .append("uom", "cm");
canvas.put("size", size);

collection.insertOne(canvas);
copy 
db.collection('inventory').insertOne({
  item: "canvas",
  qty: 100,
  tags: ["cotton"],
  size: { h: 28, w: 35.5, uom: "cm" }
})
.then(function(result) {
  // process result
})
copy 
$insertOneResult = $db->inventory->insertOne([
    'item' => 'canvas',
    'qty' => 100,
    'tags' => ['cotton'],
    'size' => ['h' => 28, 'w' => 35.5, 'uom' => 'cm'],
]);
copy 
Document canvas = new Document("item", "canvas")
        .append("qty", 100)
        .append("tags", singletonList("cotton"));

Document size = new Document("h", 28)
        .append("w", 35.5)
        .append("uom", "cm");
canvas.put("size", size);

Publisher<Success> insertOnePublisher = collection.insertOne(canvas);
copy 
var document = new BsonDocument
{
    { "item", "canvas" },
    { "qty", 100 },
    { "tags", new BsonArray { "cotton" } },
    { "size", new BsonDocument { { "h", 28 }, { "w", 35.5 }, { "uom", "cm" } } }
};
collection.InsertOne(document);
copy 
$db->coll("inventory")->insert_one(
    {
        item => "canvas",
        qty  => 100,
        tags => ["cotton"],
        size => { h => 28, w => 35.5, uom => "cm" }
    }
);
copy 
client[:inventory].insert_one({ item: 'canvas',
                                qty: 100,
                                tags: [ 'cotton' ],
                                size: { h: 28, w: 35.5, uom: 'cm' } })
copy 
collection.insertOne(
  Document("item" -> "canvas", "qty" -> 100, "tags" -> Seq("cotton"), "size" -> Document("h" -> 28, "w" -> 35.5, "uom" -> "cm"))
).execute()
  • Other

insertOne() returns a document that includes the newly inserted document’s _id field value. For an example of a return document, see db.collection.insertOne() reference.

insert_one() returns an instance of pymongo.results.InsertOneResult whose inserted_id field contains the _id of the newly inserted document.

insertOne() returns a promise that provides a result. The result.insertedId promise contains the _id of the newly inserted document.

Upon successful insert, the insertOne() method returns an instance of MongoDB\InsertOneResult whose getInsertedId() method returns the _id of the newly inserted document.

com.mongodb.reactivestreams.client.MongoCollection.insertOne returns a Publisher object. The Publisher inserts the document into a collection when subscribers request data.

Upon successful insert, the insert_one() method returns an instance of MongoDB::InsertOneResult whose inserted_id attribute contains the _id of the newly inserted document.

Upon successful insert, the insert_one() method returns an instance of Mongo::Operation::Result, whose inserted_id attribute contains the _id of the newly inserted document.

Upon successful insert, the collection.insertOne() method returns an instance of collection.insertOne().results(); whose inserted_id attribute contains the _id of the newly inserted document.

To retrieve the document that you just inserted, query the collection:

  • Other
copy 
db.inventory.find( { item: "canvas" } )
copy 
cursor = db.inventory.find({"item": "canvas"})
copy 
FindIterable<Document> findIterable = collection.find(eq("item", "canvas"));
copy 
var cursor = db.collection('inventory').find({
  item: "canvas",
});
copy 
$cursor = $db->inventory->find(['item' => 'canvas']);
copy 
FindPublisher<Document> findPublisher = collection.find(eq("item", "canvas"));
copy 
var filter = Builders<BsonDocument>.Filter.Eq("item", "canvas");
var result = collection.Find(filter).ToList();
copy 
$cursor = $db->coll("inventory")->find( { item => "canvas" } );
copy 
client[:inventory].find(item: 'canvas')
copy 
val observable = collection.find(equal("item", "canvas"))

Insert Multiple Documents

New in version 3.2.

  • Other

db.collection.insertMany() can insert multiple documents into a collection. Pass an array of documents to the method.

The following example inserts three new documents into the inventory collection. If the documents do not specify an _id field, MongoDB adds the _id field with an ObjectId value to each document. See Insert Behavior.

pymongo.collection.Collection.insert_many() can insert multiple documents into a collection. Pass an iterable of documents to the method.

The following example inserts three new documents into the inventory collection. If the documents do not specify an _id field, the PyMongo driver adds the _id field with an ObjectId value to each document. See Insert Behavior.

com.mongodb.client.MongoCollection.insertMany can insert multiple documents into a collection. Pass a list of documents to the method.

The following example inserts three new documents into the inventory collection. If the documents do not specify an _id field, the driver adds the _id field with an ObjectId value to each document. See Insert Behavior.

Collection.insertMany() can insert multiple documents into a collection. Pass an array of documents to the method.

The following example inserts three new documents into the inventory collection. If the documents do not specify an _id field, the Node.js driver adds the _id field with an ObjectId value to each document. See Insert Behavior.

MongoDB\Collection::insertMany() can insert multiple documents into a collection. Pass an array of documents to the method.

The following example inserts three new documents into the inventory collection. If the documents do not specify an _id field, the PHP driver adds the _id field with an ObjectId value to each document. See Insert Behavior.

com.mongodb.reactivestreams.client.MongoCollection.html.insertMany inserts the following documents with the Java Reactive Streams Driver:

copy 
{ item: "journal", qty: 25, tags: ["blank", "red"], size: { h: 14, w: 21, uom: "cm" } }
{ item: "mat", qty: 85, tags: ["gray"], size: { h: 27.9, w: 35.5, uom: "cm" } }
{ item: "mousepad", qty: 25, tags: ["gel", "blue"], size: { h: 19, w: 22.85, uom: "cm" } }

The following example inserts three new documents into the inventory collection. If the documents do not specify an _id field, the driver adds the _id field with an ObjectId value to each document. See Insert Behavior.

IMongoCollection.InsertMany() can insert multiple documents into a collection. Pass an enumerable collection of documents to the method.

The following example inserts three new documents into the inventory collection. If the documents do not specify an _id field, the driver adds the _id field with an ObjectId value to each document. See Insert Behavior.

MongoDB::Collection::insert_many() can insert multiple documents into a collection. Pass an array reference of documents to the method.

The following example inserts three new documents into the inventory collection. If the documents do not specify an _id field, the Perl driver adds the _id field with an ObjectId value to each document. See Insert Behavior.

Mongo::Collection#insert_many() can insert multiple documents into a collection. Pass an array of documents to the method.

The following example inserts three new documents into the inventory collection. If the documents do not specify an _id field, the Ruby driver adds the _id field with an ObjectId value to each document. See Insert Behavior.

collection.insertMany() can insert multiple documents into a collection.

The following example inserts three new documents into the inventory collection. If the documents do not specify an _id field, the Scala driver adds the _id field with an ObjectId value to each document. See Insert Behavior.

  • Other
copy 
db.inventory.insertMany([
   { item: "journal", qty: 25, tags: ["blank", "red"], size: { h: 14, w: 21, uom: "cm" } },
   { item: "mat", qty: 85, tags: ["gray"], size: { h: 27.9, w: 35.5, uom: "cm" } },
   { item: "mousepad", qty: 25, tags: ["gel", "blue"], size: { h: 19, w: 22.85, uom: "cm" } }
])

You can run the operation in the web shell below:

copy 
db.inventory.insert_many([
    {"item": "journal",
     "qty": 25,
     "tags": ["blank", "red"],
     "size": {"h": 14, "w": 21, "uom": "cm"}},
    {"item": "mat",
     "qty": 85,
     "tags": ["gray"],
     "size": {"h": 27.9, "w": 35.5, "uom": "cm"}},
    {"item": "mousepad",
     "qty": 25,
     "tags": ["gel", "blue"],
     "size": {"h": 19, "w": 22.85, "uom": "cm"}}])
copy 
Document journal = new Document("item", "journal")
        .append("qty", 25)
        .append("tags", asList("blank", "red"));

Document journalSize = new Document("h", 14)
        .append("w", 21)
        .append("uom", "cm");
journal.put("size", journalSize);

Document mat = new Document("item", "mat")
        .append("qty", 85)
        .append("tags", singletonList("gray"));

Document matSize = new Document("h", 27.9)
        .append("w", 35.5)
        .append("uom", "cm");
mat.put("size", matSize);

Document mousePad = new Document("item", "mousePad")
        .append("qty", 25)
        .append("tags", asList("gel", "blue"));

Document mousePadSize = new Document("h", 19)
        .append("w", 22.85)
        .append("uom", "cm");
mousePad.put("size", mousePadSize);

collection.insertMany(asList(journal, mat, mousePad));
copy 
db.collection('inventory').insertMany([
  { item: "journal",
    qty: 25,
    tags: ["blank", "red"],
    size: { h: 14, w: 21, uom: "cm" }},
  { item: "mat",
    qty: 85,
    tags: ["gray"],
    size: { h: 27.9, w: 35.5, uom: "cm" }},
  { item: "mousepad",
    qty: 25,
    tags: ["gel", "blue"],
    size: { h: 19, w: 22.85, uom: "cm" }}
])
.then(function(result) {
  // process result
})
copy 
$insertManyResult = $db->inventory->insertMany([
    [
        'item' => 'journal', 
        'qty' => 25,
        'tags' => ['blank', 'red'],
        'size' => ['h' => 14, 'w' => 21, 'uom' => 'cm'],
    ],
    [
        'item' => 'mat', 
        'qty' => 85,
        'tags' => ['gray'],
        'size' => ['h' => 27.9, 'w' => 35.5, 'uom' => 'cm'],
    ],
    [
        'item' => 'mousepad', 
        'qty' => 25,
        'tags' => ['gel', 'blue'],
        'size' => ['h' => 19, 'w' => 22.85, 'uom' => 'cm'],
    ],
]);
copy 
Document journal = new Document("item", "journal")
        .append("qty", 25)
        .append("tags", asList("blank", "red"));

Document journalSize = new Document("h", 14)
        .append("w", 21)
        .append("uom", "cm");
journal.put("size", journalSize);

Document mat = new Document("item", "mat")
        .append("qty", 85)
        .append("tags", singletonList("gray"));

Document matSize = new Document("h", 27.9)
        .append("w", 35.5)
        .append("uom", "cm");
mat.put("size", matSize);

Document mousePad = new Document("item", "mousePad")
        .append("qty", 25)
        .append("tags", asList("gel", "blue"));

Document mousePadSize = new Document("h", 19)
        .append("w", 22.85)
        .append("uom", "cm");
mousePad.put("size", mousePadSize);

Publisher<Success> insertManyPublisher = collection.insertMany(asList(journal, mat, mousePad));
copy 
var documents = new BsonDocument[]
{
    new BsonDocument
    {
        { "item", "journal" },
        { "qty", 25 },
        { "tags", new BsonArray { "blank", "red" } },
        { "size", new BsonDocument { { "h", 14 }, { "w", 21 }, {  "uom", "cm"} } }
    },
    new BsonDocument
    {
        { "item", "mat" },
        { "qty", 85 },
        { "tags", new BsonArray { "gray" } },
        { "size", new BsonDocument { { "h", 27.9 }, { "w", 35.5 }, {  "uom", "cm"} } }
    },
    new BsonDocument
    {
        { "item", "mousepad" },
        { "qty", 25 },
        { "tags", new BsonArray { "gel", "blue" } },
        { "size", new BsonDocument { { "h", 19 }, { "w", 22.85 }, {  "uom", "cm"} } }
    },
};
collection.InsertMany(documents);
copy 
$db->coll("inventory")->insert_many(
    [
        {
            item => "journal",
            qty  => 25,
            tags => [ "blank", "red" ],
            size => { h => 14, w => 21, uom => "cm" }
        },
        {
            item => "mat",
            qty  => 85,
            tags => ["gray"],
            size => { h => 27.9, w => 35.5, uom => "cm" }
        },
        {
            item => "mousepad",
            qty  => 25,
            tags => [ "gel", "blue" ],
            size => { h => 19, w => 22.85, uom => "cm" }
        }
    ]
);
copy 
client[:inventory].insert_many([{ item: 'journal',
                                  qty: 25,
                                  tags: ['blank', 'red'],
                                  size: { h: 14, w: 21, uom: 'cm' }
                                },
                                { item: 'mat',
                                  qty: 85,
                                  tags: ['gray'],
                                  size: { h: 27.9, w: 35.5, uom: 'cm' }
                                },
                                { item: 'mousepad',
                                  qty: 25,
                                  tags: ['gel', 'blue'],
                                  size: { h: 19, w: 22.85, uom: 'cm' }
                                }
                               ])
copy 
collection.insertMany(Seq(
  Document("item" -> "journal", "qty" -> 25, "tags" -> Seq("blank", "red"), "size" -> Document("h" -> 14, "w" -> 21, "uom" -> "cm")),
  Document("item" -> "mat", "qty" -> 85, "tags" -> Seq("gray"), "size" -> Document("h" -> 27.9, "w" -> 35.5, "uom" -> "cm")),
  Document("item" -> "mousepad", "qty" -> 25, "tags" -> Seq("gel", "blue"), "size" -> Document("h" -> 19, "w" -> 22.85, "uom" -> "cm"))
)).execute()
  • Other

insertMany() returns a document that includes the newly inserted documents _id field values. See the reference for an example.

insert_many() returns an instance of pymongo.results.InsertManyResult whose inserted_ids field is a list containing the _id of each newly inserted document.

insertMany() returns a promise that provides a result. The result.insertedIds field contains an array with the _id of each newly inserted document.

Upon successful insert, the insertMany() method returns an instance of MongoDB\InsertManyResult whose getInsertedIds() method returns the _id of each newly inserted document.

com.mongodb.reactivestreams.client.MongoCollection.html.insertMany returns a Publisher object. The Publisher inserts the document into a collection when subscribers request data.

Upon successful insert, the insert_many() method returns an instance of MongoDB::InsertManyResult whose inserted_ids attribute is a list containing the _id of each newly inserted document.

Upon successful insert, the insert_many() method returns an instance of Mongo::BulkWrite::Result whose inserted_ids attribute is a list containing the _id of each newly inserted document.

Upon successful insert, the insertMany() method returns an Observable with a type parameter indicating when the operation has completed or with either a com.mongodb.DuplicateKeyException or com.mongodb.MongoException.

To retrieve the inserted documents, query the collection:

  • Other
copy 
db.inventory.find( {} )
copy 
cursor = db.inventory.find({})
copy 
FindIterable<Document> findIterable = collection.find(new Document());
copy 
var cursor = db.collection('inventory').find({});
copy 
$cursor = $db->inventory->find([]);
copy 
FindPublisher<Document> findPublisher = collection.find(new Document());
copy 
var filter = Builders<BsonDocument>.Filter.Empty;
var result = collection.Find(filter).ToList();
copy 
$cursor = $db->coll("inventory")->find( {} );
copy 
client[:inventory].find({})
copy 
var findObservable = collection.find(Document())

Insert Behavior

Collection Creation

If the collection does not currently exist, insert operations will create the collection.

_id Field

In MongoDB, each document stored in a collection requires a unique _id field that acts as a primary key. If an inserted document omits the _id field, the MongoDB driver automatically generates an ObjectId for the _id field.

This also applies to documents inserted through update operations with upsert: true.

Atomicity

All write operations in MongoDB are atomic on the level of a single document. For more information on MongoDB and atomicity, see Atomicity and Transactions

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.