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()