- Reference >
mongo
Shell Methods >- Collection Methods >
- db.collection.insertOne()
db.collection.insertOne()¶
On this page
Definition¶
-
db.collection.
insertOne
()¶ New in version 3.2.
Inserts a document into a collection.
The
insertOne()
method has the following syntax:Parameter Type Description document
document A document to insert into the collection. writeConcern
document Optional. A document expressing the write concern. Omit to use the default write concern. Returns: A document containing: - A boolean
acknowledged
astrue
if the operation ran with write concern orfalse
if write concern was disabled. - A field
insertedId
with the_id
value of the inserted document.
- A boolean
Behaviors¶
Collection Creation¶
If the collection does not exist, then the
insertOne()
method creates the collection.
_id
Field¶
If the document does not specify an _id field, then mongod
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 contains an _id
field, the _id
value must be
unique within the collection to avoid duplicate key error.
Error Handling¶
On error, insertOne()
throws either a writeError
or writeConcernError
exception.
Examples¶
Insert a Document without Specifying an _id
Field¶
In the following example, the document passed to the
insertOne()
method does not contain the _id
field:
The operation returns the following document:
Because the documents did not include _id
,
mongod
creates and adds the _id
field and
assigns 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.
Insert a Document Specifying an _id
Field¶
In the following example, the document passed to the
insertOne()
method includes the _id
field.
The value of _id
must be unique within the collection to avoid
duplicate key error.
The operation returns the following:
Inserting an duplicate value for any key that is part of a unique
index, such as _id
, throws an exception. The following attempts to insert
a document with a _id
value that already exists:
Since _id: 10
already exists, the following exception is thrown:
Increase Write Concern¶
Given a three member replica set, the following operation specifies a
w
of majority
, wtimeout
of 100
:
If the acknowledgement takes longer than the wtimeout
limit, the following
exception is thrown:
See also
To insert multiple documents, see
db.collection.insertMany()