- Core MongoDB Operations (CRUD) >
- Create
Create¶
On this page
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 themongod
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.
- The field name
Note
As of these driver versions, all
write operations will issue a getLastError
command to
confirm the result of the write operation:
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:
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:
You can confirm the insert by querying
the bios
collection:
This operation returns the following document from the bios
collection:
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:
You can verify the inserted document by the querying the bios
collection:
The returned document contains an _id
field with the generated
ObjectId
value:
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:
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:
[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]:
[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]:
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]:
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
: