Fix This Page
Navigation

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.

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.

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.

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.

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:

db.inventory.insert_one(
    {"item": "canvas",
     "qty": 100,
     "tags": ["cotton"],
     "size": {"h": 28, "w": 35.5, "uom": "cm"}})
$insertOneResult = $db->inventory->insertOne([
    'item' => 'canvas',
    'qty' => 100,
    'tags' => ['cotton'],
    'size' => ['h' => 28, 'w' => 35.5, 'uom' => 'cm'],
]);
$db->coll("inventory")->insert_one(
    {
        item => "canvas",
        qty  => 100,
        tags => ["cotton"],
        size => { h => 28, w => 35.5, uom => "cm" }
    }
);

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.

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

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.

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

db.inventory.find( { item: "canvas" } )
cursor = db.inventory.find({"item": "canvas"})
$cursor = $db->inventory->find(['item' => 'canvas']);
$cursor = $db->coll("inventory")->find( { item => "canvas" } );

Insert Multiple Documents

New in version 3.2.

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.

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.

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.

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:

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"}}])
$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'],
    ],
]);
$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" }
        }
    ]
);

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.

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

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.

To retrieve the inserted documents, query the collection:

db.inventory.find( {} )
cursor = db.inventory.find({})
$cursor = $db->inventory->find([]);
$cursor = $db->coll("inventory")->find( {} );

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