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

Create

Of the four basic database operations (i.e. CRUD), create operations are those that add new records or documents to a collection in MongoDB. For general information about write operations and the factors that affect their performance, see Write Operations; for documentation of the other CRUD operations, see the Core MongoDB Operations (CRUD) page.

Overview

You can create documents in a MongoDB collection using any of the following basic operations:

All insert operations in MongoDB exhibit the following properties:

  • If you attempt to insert a document without the _id field, the client library or the mongod instance will add an _id field and populate the field with a unique ObjectId.

  • For operations with write concern, if you specify an _id field, the _id field must be unique within the collection; otherwise the mongod will return a duplicate key exception.

  • The maximum BSON document size is 16 megabytes.

    The maximum document size helps ensure that a single document cannot use excessive amount of RAM or, during transmission, excessive amount of bandwidth. To store documents larger than the maximum size, MongoDB provides the GridFS API. See mongofiles and the documentation for your driver for more information about GridFS.

  • Documents have the following restrictions on field names:

    • The field name _id is reserved for use as a primary key; its value must be unique in the collection, is immutable, and may be of any type other than an array.
    • The field names cannot start with the $ character.
    • The field names cannot contain the . character.

Note

As of these driver versions, all write operations will issue a getLastError command to confirm the result of the write operation:

{ getLastError: 1 }

Refer to the documentation on write concern in the Write Operations document for more information.

insert()

The insert() is the primary method to insert a document or documents into a MongoDB collection, and has the following syntax:

db.collection.insert( <document> )

Corresponding Operation in SQL

The insert() method is analogous to the INSERT statement.

Insert the First Document in a Collection

If the collection does not exist [1], then the insert() method creates the collection during the first insert. Specifically in the example, if the collection bios does not exist , then the insert operation will create this collection:

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'
               }
             ]
   }
)

You can confirm the insert by querying the bios collection:

db.bios.find()

This operation returns the following document from the bios collection:

{
  "_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 a Document without Specifying an _id Field

If the new document does not contain an _id field, then the insert() method adds the _id field to the document and generates a unique ObjectId for the value:

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'
               }
             ]
   }
)

You can verify the inserted document by the querying the bios collection:

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

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

{
  "_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,
                 "by" : "Inamori Foundation"
               },
               {
                 "award" : "National Medal of Science",
                 "year" : 1990,
                 "by" : "National Science Foundation"
               }
             ]
}

Bulk Insert Multiple Documents

If you pass an array of documents to the insert() method, the insert() performs a bulk insert into a collection.

The following operation inserts three documents into the bios collection. The operation also illustrates the dynamic schema characteristic of MongoDB. Although the document with _id: 3 contains a field title which does not appear in the other documents, MongoDB does not require the other documents to contain this field:

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'
                 }
               ]
     }
   ]
)

Insert a Document with save()

The save() method performs an insert if the document to save does not contain the _id field.

The following save() operation performs an insert into the bios collection since the document does not contain the _id field:

db.bios.save(
   {
        name: { first: 'Guido', last: 'van Rossum'},
        birth: new Date('Jan 31, 1956'),
        contribs: [ 'Python' ],
        awards: [
                  {
                    award: 'Award for the Advancement of Free Software',
                    year: 2001,
                    by: 'Free Software Foundation'
                  },
                  {
                    award: 'NLUUG Award',
                    year: 2003,
                    by: 'NLUUG'
                  }
                ]
   }
)
[1]You can also view a list of the existing collections in the database using the show collections operation in the mongo shell.

update() Operations with the upsert Flag

The update() operation in MongoDB accepts an “upsert” flag that modifies the behavior of update() from updating existing documents, to inserting data.

These update() operations with the upsert flag eliminate the need to perform an additional operation to check for existence of a record before performing either an update or an insert operation. These update operations have the use <query> argument to determine the write operation:

  • If the query matches an existing document(s), the operation is an update.
  • If the query matches no document in the collection, the operation is an insert.

An upsert operation has the following syntax [2]:

db.collection.update( <query>,
                      <update>,
                      { upsert: true } )
[2](1, 2, 3) Prior to version 2.2, in the mongo shell, you would specify the upsert and the multi options in the update() method as positional boolean options. See update() for details.

Insert a Document that Contains field and value Pairs

If no document matches the <query> argument, the upsert performs an insert. If the <update> argument includes only field and value pairs, the new document contains the fields and values specified in the <update> argument. If query does not include an _id field, the operation adds the _id field and generates a unique ObjectId for its value.

The following update inserts a new document into the bios collection [2]:

db.bios.update(
   { name: { first: 'Dennis', last: 'Ritchie'} },
   {
     name: { first: 'Dennis', last: 'Ritchie'},
     birth: new Date('Sep 09, 1941'),
     death: new Date('Oct 12, 2011'),
     contribs: [ 'UNIX', 'C' ],
     awards: [
               {
                 award: 'Turing Award',
                 year: 1983,
                 by: 'ACM'
               },
               {
                 award: 'National Medal of Technology',
                 year: 1998,
                 by: 'United States'
               },
               {
                 award: 'Japan Prize',
                 year: 2011,
                 by: 'The Japan Prize Foundation'
               }
             ]
   },
   { upsert: true }
)

Insert a Document that Contains Update Operator Expressions

If no document matches the <query> argument, the update operation inserts a new document. If the <update> argument includes only update operators, the new document contains the fields and values from <query> argument with the operations from the <update> argument applied.

The following operation inserts a new document into the bios collection [2]:

db.bios.update(
   {
     _id: 7,
     name: { first: 'Ken', last: 'Thompson' }
   },
   {
     $set: {
             birth: new Date('Feb 04, 1943'),
             contribs: [ 'UNIX', 'C', 'B', 'UTF-8' ],
             awards: [
                       {
                         award: 'Turing Award',
                         year: 1983,
                         by: 'ACM'
                       },
                       {
                         award: 'IEEE Richard W. Hamming Medal',
                         year: 1990,
                         by: 'IEEE'
                       },
                       {
                         award: 'National Medal of Technology',
                         year: 1998,
                         by: 'United States'
                       },
                       {
                         award: 'Tsutomu Kanai Award',
                         year: 1999,
                         by: 'IEEE'
                       },
                       {
                         award: 'Japan Prize',
                         year: 2011,
                         by: 'The Japan Prize Foundation'
                       }
                     ]
           }
   },
   { upsert: true }
)

Update operations with save()

The save() method is identical to an update operation with the upsert flag

performs an upsert if the document to save contains the _id field. To determine whether to perform an insert or an update, save() method queries documents on the _id field.

The following operation performs an upsert that inserts a document into the bios collection since no documents in the collection contains an _id field with the value 10:

db.bios.save(
   {
     _id: 10,
     name: { first: 'Yukihiro', aka: 'Matz', last: 'Matsumoto'},
     birth: new Date('Apr 14, 1965'),
     contribs: [ 'Ruby' ],
     awards: [
               {
                 award: 'Award for the Advancement of Free Software',
                 year: '2011',
                 by: 'Free Software Foundation'
               }
             ]
   }
)
←   GridFS Read  →