• Reference >
• mongo Shell Methods >
• Collection Methods >
• db.collection.insert()

db.collection.insert()

Definition

db.collection.insert(document)

Inserts a document or an array of documents into a collection.

Changed in version 2.2: The insert() method can accept an array of documents to perform a bulk insert of the documents into the collection.

Parameter	Type	Description
document	document or array	A document or array of documents to insert into the collection.

The insert() method has the following behaviors:

• If the collection does not exist, then the insert() method will create the collection.
• If the document does not specify an _id field, then MongoDB will add the _id field and assign a unique ObjectId for the document before inserting. Most drivers create an ObjectId and insert the _id field, but the mongod will create and populate the _id if the driver or application does not.
• If the document specifies a new field, then the insert() method inserts the document with the new field. This requires no changes to the data model for the collection or the existing documents.

Examples

The following examples show how to use the insert() method to insert a document or an array of documents into either the products collection or the bios collection. If the collections do not exist, the insert() method creates the collections. [1]

Insert a Document without Specifying an _id Field

In the following examples, the document passed to the insert() method does not contain the _id field. During the insert, mongod will create the _id field and assign it a unique ObjectId value.

The ObjectId values are specific to the machine and time when the operation is run. As such, your values may differ from those in the example.

products Collection

The following example inserts a document into the products collection:

copy

db.products.insert( { item: "card", qty: 15 } )

The inserted document includes an _id field with the generated ObjectId value:

copy

{ "_id" : ObjectId("5063114bd386d8fadbd6b004"), "item" : "card", "qty" : 15 }

bios Collection

The following example inserts a document into the The bios Example Collection:

copy

db.bios.insert(
   {
     name: { first: 'John', last: 'McCarthy' },
     birth: new Date('Sep 04, 1927'),
     death: new Date('Dec 24, 2011'),
     contribs: [ 'Lisp', 'Artificial Intelligence', 'ALGOL' ],
     awards: [
               {
                 award: 'Turing Award',
                 year: 1971,
                 by: 'ACM'
               },
               {
                 award: 'Kyoto Prize',
                 year: 1988,
                 by: 'Inamori Foundation'
               },
               {
                 award: 'National Medal of Science',
                 year: 1990,
                 by: 'National Science Foundation'
               }
             ]
   }
)

To verify the inserted document, query the bios collection:

copy

db.bios.find( { name: { first: 'John', last: 'McCarthy' } } )

The returned document includes an _id field with the generated ObjectId value:

copy

{
  "_id" : ObjectId("50a1880488d113a4ae94a94a"),
  "name" : { "first" : "John", "last" : "McCarthy" },
  "birth" : ISODate("1927-09-04T04:00:00Z"),
  "death" : ISODate("2011-12-24T05:00:00Z"),
  "contribs" : [ "Lisp", "Artificial Intelligence", "ALGOL" ],
  "awards" : [
               {
                 "award" : "Turing Award",
                 "year" : 1971,
                 "by" : "ACM"
               },
               {
                 "award" : "Kyoto Prize",
                 "year" :1988,s
                 "by" : "Inamori Foundation"
               },
               {
                 "award" : "National Medal of Science",
                 "year" : 1990,
                 "by" : "National Science Foundation"
               }
             ]
}

Note

Most MongoDB driver clients will include the _id field and generate an ObjectId before sending the insert operation to MongoDB; however, if the client sends a document without an _id field, the mongod will add the _id field and generate the ObjectId.

Insert a Document Specifying an _id Field

In the following examples, the documents passed to the insert() method includes the _id field. The value of _id must be unique within the collection to avoid duplicate key error.

products Collection

This example inserts into the products collection a document that includes an _id field. The _id value of 10 must be a unique value for the _id field in the products collection. If the value were not unique, the insert would fail:

copy

db.products.insert( { _id: 10, item: "box", qty: 20 } )

The insert operation creates the following document in the products collection:

copy

{ "_id" : 10, "item" : "box", "qty" : 20 }

bios Collection

This example inserts into the bios collection a document that includes an _id field. The _id value of 1 must be a unique value for the _id field in the bios collection. Otherwise, if the value were not unique, the insert would fail:

copy

db.bios.insert(
   {
     _id: 1,
     name: { first: 'John', last: 'Backus' },
     birth: new Date('Dec 03, 1924'),
     death: new Date('Mar 17, 2007'),
     contribs: [ 'Fortran', 'ALGOL', 'Backus-Naur Form', 'FP' ],
     awards: [
               {
                 award: 'W.W. McDowell Award',
                 year: 1967,
                 by: 'IEEE Computer Society'
               },
               {
                 award: 'National Medal of Science',
                 year: 1975,
                 by: 'National Science Foundation'
               },
               {
                 award: 'Turing Award',
                 year: 1977,
                 by: 'ACM'
               },
               {
                 award: 'Draper Prize',
                 year: 1993,
                 by: 'National Academy of Engineering'
               }
             ]
   }
)

To confirm the insert, query the bios collection:

copy

db.bios.find( { _id: 1 } )

The insert operation created the following document in the bios collection:

copy

{
  "_id" : 1,
  "name" : { "first" : "John", "last" : "Backus" },
  "birth" : ISODate("1924-12-03T05:00:00Z"),
  "death" : ISODate("2007-03-17T04:00:00Z"),
  "contribs" : [ "Fortran", "ALGOL", "Backus-Naur Form", "FP" ],
  "awards" : [
               {
                 "award" : "W.W. McDowell Award",
                 "year" : 1967,
                 "by" : "IEEE Computer Society"
               },
               {
                 "award" : "National Medal of Science",
                 "year" : 1975,
                 "by" : "National Science Foundation"
               },
               {
                 "award" : "Turing Award",
                 "year" : 1977,
                 "by" : "ACM"
               },
               { "award" : "Draper Prize",
                 "year" : 1993,
                 "by" : "National Academy of Engineering"
               }
             ]
}

Insert Multiple Documents

The following examples perform a bulk insert of multiple documents by passing an array of documents to the insert() method.

products Collection

This example inserts three documents into the products collection. The documents in the array do not need to have the same fields. For instance, the first document in the array has an _id field and a type field. Because the second and third documents do not contain an _id field, mongod will create the _id field for the second and third documents during the insert:

copy

db.products.insert( [ { _id: 11, item: "pencil", qty: 50, type: "no.2" },
                      {          item: "pen", qty: 20 },
                      {          item: "eraser", qty: 25 }
                    ] )

The operation inserted the following three documents:

copy

{ "_id" : 11, "item" : "pencil", "qty" : 50, "type" : "no.2" }
{ "_id" : ObjectId("51e0373c6f35bd826f47e9a0"), "item" : "pen", "qty" : 20 }
{ "_id" : ObjectId("51e0373c6f35bd826f47e9a1"), "item" : "eraser", "qty" : 25 }.

bios Collection

This example inserts three documents in the bios collection. The documents in the array do not need to have the same fields. The document with _id: 3 contains a field named title that does not appear in the other documents. MongoDB does not require the other documents to contain this field:

copy

db.bios.insert(
   [
     {
       _id: 3,
       name: { first: 'Grace', last: 'Hopper' },
       title: 'Rear Admiral',
       birth: new Date('Dec 09, 1906'),
       death: new Date('Jan 01, 1992'),
       contribs: [ 'UNIVAC', 'compiler', 'FLOW-MATIC', 'COBOL' ],
       awards: [
                 {
                   award: 'Computer Sciences Man of the Year',
                   year: 1969,
                   by: 'Data Processing Management Association'
                 },
                 {
                   award: 'Distinguished Fellow',
                   year: 1973,
                   by: ' British Computer Society'
                 },
                 {
                   award: 'W. W. McDowell Award',
                   year: 1976,
                   by: 'IEEE Computer Society'
                 },
                 {
                   award: 'National Medal of Technology',
                   year: 1991,
                   by: 'United States'
                 }
               ]
     },
     {
       _id: 4,
       name: { first: 'Kristen', last: 'Nygaard' },
       birth: new Date('Aug 27, 1926'),
       death: new Date('Aug 10, 2002'),
       contribs: [ 'OOP', 'Simula' ],
       awards: [
                 {
                   award: 'Rosing Prize',
                   year: 1999,
                   by: 'Norwegian Data Association'
                 },
                 {
                   award: 'Turing Award',
                   year: 2001,
                   by: 'ACM'
                 },
                 {
                   award: 'IEEE John von Neumann Medal',
                   year: 2001,
                   by: 'IEEE'
                 }
               ]
     },
     {
       _id: 5,
       name: { first: 'Ole-Johan', last: 'Dahl' },
       birth: new Date('Oct 12, 1931'),
       death: new Date('Jun 29, 2002'),
       contribs: [ 'OOP', 'Simula' ],
       awards: [
                 {
                   award: 'Rosing Prize',
                   year: 1999,
                   by: 'Norwegian Data Association'
                 },
                 {
                   award: 'Turing Award',
                   year: 2001,
                   by: 'ACM'
                 },
                 {
                   award: 'IEEE John von Neumann Medal',
                   year: 2001,
                   by: 'IEEE'
                 }
               ]
     }
   ]
)

[1]	You can also view a list of the existing collections in the database using the show collections operation in the mongo shell.

←   db.collection.group() db.collection.isCapped()  →

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