Permalink
Fetching contributors…
Cannot retrieve contributors at this time
527 lines (399 sloc) 19 KB
.. include:: /includes/templates/tabs.rst
.. include:: /includes/java-sync-links.rst
.. _write-op-insert:
================
Insert Documents
================
.. default-domain:: mongodb
.. meta::
:description: Insert documents using MongoDB. Creates collection upon first insert.
:keywords: insert documents, create documents, insert into collection, create collection, MongoDB 3.4, version 3.4
This page provides examples of insert operations in MongoDB.
.. admonition:: Creating a Collection
:class: note
If the collection does not currently exist, insert operations will
create the collection.
.. _write-op-insertOne:
Insert a Single Document
------------------------
.. versionadded:: 3.2
.. tabs::
tabs:
- id: shell
content: |
:method:`db.collection.insertOne()` inserts a *single*
:ref:`document<bson-document-format>` into a collection.
The following example inserts a new document into the
``inventory`` collection. If the document does not specify
an ``_id`` field, MongoDB adds the ``_id`` field with an
ObjectId value to the new document. See
:ref:`write-op-insert-behavior`.
- id: python
content: |
:py:meth:`pymongo.collection.Collection.insert_one` inserts a
*single* :ref:`document<bson-document-format>` into a
collection.
The following example inserts a new document into the
``inventory`` collection. If the document does not specify
an ``_id`` field, the PyMongo driver adds the ``_id`` field
with an ObjectId value to the new document. See
:ref:`write-op-insert-behavior`.
- id: java-sync
content: |
com.mongodb.client.MongoCollection.insertOne_
inserts a *single* :ref:`document<bson-document-format>` into
a collection.
The following example inserts a new document into the
``inventory`` collection. If the document does not specify
an ``_id`` field, the driver adds the ``_id`` field with an
ObjectId value to the new document. See
:ref:`write-op-insert-behavior`.
- id: nodejs
content: |
:node-api:`Collection.insertOne() <Collection.html#insertOne>`
inserts a *single* :ref:`document<bson-document-format>` into a
collection.
The following example inserts a new document into the
``inventory`` collection. If the document does not specify
an ``_id`` field, the Node.js driver adds the ``_id`` field
with an ObjectId value to the new document. See
:ref:`write-op-insert-behavior`.
- id: php
content: |
:phpmethod:`MongoDB\\Collection::insertOne() <phpmethod.MongoDB\\Collection::insertOne>`
inserts a *single* :ref:`document<bson-document-format>` into a
collection.
The following example inserts a new document into the
``inventory`` collection. If the document does not specify
an ``_id`` field, the PHP driver adds the ``_id`` field
with an ObjectId value to the new document. See
:ref:`write-op-insert-behavior`.
- id: perl
content: |
:perl-api:`MongoDB::Collection::insert_one()<Collection#insert_one>`
inserts a *single* :ref:`document<bson-document-format>` into a
collection.
The following example inserts a new document into the
``inventory`` collection. If the document does not specify
an ``_id`` field, the Perl driver adds the ``_id`` field
with an ObjectId value to the new document. See
:ref:`write-op-insert-behavior`.
- id: ruby
content: |
:ruby-api:`Mongo::Collection#insert_one()<Collection.html#insert_one-instance_method>`
inserts a *single* :ref:`document<bson-document-format>` into a
collection.
The following example inserts a new document into the
``inventory`` collection. If the document does not specify
an ``_id`` field, the Ruby driver adds the ``_id`` field
with an ObjectId value to the new document. See
:ref:`write-op-insert-behavior`.
- id: scala
content: |
:scala-api:`collection.insertOne()<insertOne(document:TResult,options:org.mongodb.scala.model.InsertOneOptions):org.mongodb.scala.SingleObservable[org.mongodb.scala.Completed]>`
inserts a *single* :ref:`document<bson-document-format>` into a
collection.
The following example inserts a new document into the
``inventory`` collection. If the document does not specify
an ``_id`` field, the Scala driver adds the ``_id`` field
with an ObjectId value to the new document. See
:ref:`write-op-insert-behavior`.
- id: csharp
content: |
:csharp-api:`IMongoCollection.InsertOne() <M_MongoDB_Driver_IMongoCollection_1_InsertOne>`
inserts a *single* :ref:`document<bson-document-format>` into a
collection.
The following example inserts a new document into the
``inventory`` collection. If the document does not specify
an ``_id`` field, the C# driver adds the ``_id`` field
with an ObjectId value to the new document. See
:ref:`write-op-insert-behavior`.
.. include:: /includes/driver-example-insert-1.rst
.. tabs::
tabs:
- id: shell
content: |
:method:`~db.collection.insertOne()` returns a document that
includes the newly inserted document's ``_id`` field value. For
an example of a return document, see
:ref:`db.collection.insertOne() reference<insertOne-examples>`.
- id: python
content: |
:py:meth:`~pymongo.collection.Collection.insert_one` returns an
instance of :py:class:`pymongo.results.InsertOneResult` whose
``inserted_id`` field contains the ``_id`` of the newly
inserted document.
- id: java-sync
content: |
- id: nodejs
content: |
:node-api:`insertOne() <Collection.html#insertOne>` returns a
promise that provides a ``result``. The ``result.insertedId``
promise contains the ``_id`` of the newly inserted document.
- id: php
content: |
Upon successful insert, the
:phpmethod:`insertOne() <phpmethod.MongoDB\\Collection::insertOne>`
method returns an instance of
:phpclass:`MongoDB\\InsertOneResult <phpclass.MongoDB\\InsertOneResult>`
whose
:phpmethod:`getInsertedId() <phpmethod.MongoDB\\InsertOneResult::getInsertedId>`
method returns the ``_id`` of the newly inserted document.
- id: perl
content: |
Upon successful insert, the
:perl-api:`insert_one()<Collection#insert_one>` method returns
an instance of
:perl-api:`MongoDB::InsertOneResult<InsertOneResult>` whose
``inserted_id`` attribute contains the ``_id`` of the newly
inserted document.
- id: ruby
content: |
Upon successful insert, the
:ruby-api:`insert_one()<Collection.html#insert_one-instance_method>`
method returns an instance of
:ruby-api:`Mongo::Operation::Result<Operation/Result.html>`, whose
``inserted_id`` attribute contains the ``_id`` of the newly
inserted document.
- id: scala
content: |
Upon successful insert, the
:scala-api:`collection.insertOne()<MongoCollection.html#insertOne(document:TResult,options:org.mongodb.scala.model.InsertOneOptions):org.mongodb.scala.SingleObservable[org.mongodb.scala.Completed]>`
method returns an instance of
:scala-api:`collection.insertOne().results();<InsertOneResult>` whose
``inserted_id`` attribute contains the ``_id`` of the newly
inserted document.
- id: csharp
content: |
To retrieve the document that you just inserted, :ref:`query the collection
<document-query-filter>`:
.. include:: /includes/driver-example-insert-2.rst
.. _write-op-insertMany:
Insert Multiple Documents
-------------------------
.. versionadded:: 3.2
.. tabs::
tabs:
- id: shell
content: |
:method:`db.collection.insertMany()` can insert *multiple*
:ref:`documents <bson-document-format>` into a collection. Pass an
array of documents to the method.
The following example inserts three new documents into the
``inventory`` collection. If the documents do not specify an
``_id`` field, MongoDB adds the ``_id`` field with an ObjectId
value to each document. See :ref:`write-op-insert-behavior`.
- id: python
content: |
:py:meth:`pymongo.collection.Collection.insert_many` can insert
*multiple* :ref:`documents <bson-document-format>` into a
collection. Pass an iterable of documents to the method.
The following example inserts three new documents into the
``inventory`` collection. If the documents do not specify an
``_id`` field, the PyMongo driver adds the ``_id`` field with
an ObjectId value to each document. See :ref:`write-op-insert-behavior`.
- id: java-sync
content: |
com.mongodb.client.MongoCollection.insertMany_
can insert *multiple* :ref:`documents <bson-document-format>`
into a collection. Pass a list of documents to the method.
The following example inserts three new documents into the
``inventory`` collection. If the documents do not specify an
``_id`` field, the driver adds the ``_id`` field with
an ObjectId value to each document. See :ref:`write-op-insert-behavior`.
- id: nodejs
content: |
:node-api:`Collection.insertMany() <Collection.html#insertMany>`
can insert *multiple* :ref:`documents <bson-document-format>`
into a collection. Pass an array of documents to the method.
The following example inserts three new documents into the
``inventory`` collection. If the documents do not specify an
``_id`` field, the Node.js driver adds the ``_id`` field with
an ObjectId value to each document. See
:ref:`write-op-insert-behavior`.
- id: php
content: |
:phpmethod:`MongoDB\\Collection::insertMany() <phpmethod.MongoDB\\Collection::insertMany>`
can insert *multiple* :ref:`documents <bson-document-format>` into a
collection. Pass an array of documents to the method.
The following example inserts three new documents into the
``inventory`` collection. If the documents do not specify an
``_id`` field, the PHP driver adds the ``_id`` field with
an ObjectId value to each document. See :ref:`write-op-insert-behavior`.
- id: perl
content: |
:perl-api:`MongoDB::Collection::insert_many()<Collection#insert_many>`
can insert *multiple* :ref:`documents <bson-document-format>` into a
collection. Pass an array reference of documents to the method.
The following example inserts three new documents into the
``inventory`` collection. If the documents do not specify an
``_id`` field, the Perl driver adds the ``_id`` field with
an ObjectId value to each document. See :ref:`write-op-insert-behavior`.
- id: ruby
content: |
:ruby-api:`Mongo::Collection#insert_many()<Collection.html#insert_many-instance_method>`
can insert *multiple* :ref:`documents <bson-document-format>` into a
collection. Pass an array of documents to the method.
The following example inserts three new documents into the
``inventory`` collection. If the documents do not specify an
``_id`` field, the Ruby driver adds the ``_id`` field with
an ObjectId value to each document. See :ref:`write-op-insert-behavior`.
- id: scala
content: |
:scala-api:`collection.insertMany()<insertMany(documents:Seq[_<:TResult],options:org.mongodb.scala.model.InsertManyOptions):org.mongodb.scala.SingleObservable[org.mongodb.scala.Completed]>`
can insert *multiple* :ref:`documents <bson-document-format>` into a
collection.
The following example inserts three new documents into the
``inventory`` collection. If the documents do not specify an
``_id`` field, the Scala driver adds the ``_id`` field with
an ObjectId value to each document. See :ref:`write-op-insert-behavior`.
- id: csharp
content: |
:csharp-api:`IMongoCollection.InsertMany()<M_MongoDB_Driver_IMongoCollection_1_InsertMany>`
can insert *multiple* :ref:`documents <bson-document-format>`
into a collection. Pass an enumerable collection of documents
to the method.
The following example inserts three new documents into the
``inventory`` collection. If the documents do not specify an
``_id`` field, the driver adds the ``_id`` field with
an ObjectId value to each document. See :ref:`write-op-insert-behavior`.
.. include:: /includes/driver-example-insert-3.rst
.. tabs::
tabs:
- id: shell
content: |
:method:`~db.collection.insertMany()` returns a document that includes
the newly inserted documents ``_id`` field values. See the
:ref:`reference <insertMany-examples>` for an example.
- id: python
content: |
:py:meth:`~pymongo.collection.Collection.insert_many` returns
an instance of :py:class:`pymongo.results.InsertManyResult`
whose ``inserted_ids`` field is a list containing the ``_id``
of each newly inserted document.
- id: java-sync
content: |
- id: nodejs
content: |
:node-api:`insertMany() <Collection.html#insertMany>` returns a
promise that provides a ``result``. The ``result.insertedIds``
field contains an array with the ``_id`` of each newly inserted
document.
- id: php
content: |
Upon successful insert, the
:phpmethod:`insertMany() <phpmethod.MongoDB\\Collection::insertMany>`
method
returns an instance of
:phpclass:`MongoDB\\InsertManyResult <phpclass.MongoDB\\InsertManyResult>`
whose
:phpmethod:`getInsertedIds() <phpmethod.MongoDB\\InsertManyResult::getInsertedIds>`
method returns the ``_id`` of each newly inserted document.
- id: perl
content: |
Upon successful insert, the
:perl-api:`insert_many()<Collection#insert_many>` method
returns an instance of
:perl-api:`MongoDB::InsertManyResult<InsertManyResult>`
whose ``inserted_ids`` attribute is a list containing the
``_id`` of each newly inserted document.
- id: ruby
content: |
Upon successful insert, the
:ruby-api:`insert_many()<Collection.html#insert_many>` method
returns an instance of
:ruby-api:`Mongo::BulkWrite::Result<BulkWrite/Result.html>`
whose ``inserted_ids`` attribute is a list containing the
``_id`` of each newly inserted document.
- id: scala
content: |
Upon successful insert, the
:scala-api:`insertMany()<insertMany(documents:Seq[_<:TResult],options:org.mongodb.scala.model.InsertManyOptions):org.mongodb.scala.SingleObservable[org.mongodb.scala.Completed]>`
method returns an `Observable <http://mongodb.github.io/mongo-scala-driver/2.1/reference/observables/>`_ with a type parameter indicating when
the operation has completed or with either a
``com.mongodb.DuplicateKeyException`` or
``com.mongodb.MongoException``.
- id: csharp
content: |
To retrieve the inserted documents, :ref:`query the collection
<read-operations-query-document>`:
.. include:: /includes/driver-example-query-7.rst
.. _write-op-insert-behavior:
Insert Behavior
---------------
Collection Creation
~~~~~~~~~~~~~~~~~~~
If the collection does not currently exist, insert operations will
create the collection.
``_id`` Field
~~~~~~~~~~~~~
.. include:: /includes/fact-id-field.rst
Atomicity
~~~~~~~~~
All write operations in MongoDB are atomic on the level of a single
document. For more information on MongoDB and atomicity, see
:doc:`/core/write-operations-atomicity`
Write Acknowledgement
~~~~~~~~~~~~~~~~~~~~~
With write concerns, you can specify the level of acknowledgement
requested from MongoDB for write operations. For details, see
:doc:`/reference/write-concern`.
.. tabs::
tabs:
- id: shell
content: |
.. seealso::
- :method:`db.collection.insertOne()`
- :method:`db.collection.insertMany()`
- :ref:`additional-inserts`
- id: python
content: |
.. seealso::
- :py:meth:`pymongo.collection.Collection.insert_one`
- :py:meth:`pymongo.collection.Collection.insert_many`
- :ref:`additional-inserts`
- id: java-sync
content: |
.. seealso::
- com.mongodb.client.MongoCollection.insertOne_
- com.mongodb.client.MongoCollection.insertMany_
- `Additional Java Synchronous Driver Write Examples`_
- id: nodejs
content: |
.. seealso::
- :node-api:`Collection.insertOne() <Collection.html#insertOne>`
- :node-api:`Collection.insertMany() <Collection.html#insertMany>`
- :ref:`additional-inserts`
- id: php
content: |
.. seealso::
- :phpmethod:`MongoDB\\Collection::insertOne() <phpmethod.MongoDB\\Collection::insertOne>`
- :phpmethod:`MongoDB\\Collection::insertMany() <phpmethod.MongoDB\\Collection::insertMany>`
- :ref:`additional-inserts`
- id: perl
content: |
.. seealso::
- :perl-api:`MongoDB::Collection::insert_one()<Collection#insert_one>`
- :perl-api:`MongoDB::Collection::insert_many()<Collection#insert_many>`
- :ref:`additional-inserts`
- id: ruby
content: |
.. seealso::
- :ruby-api:`Mongo::Collection#insert_one()<Collection.html#insert_one-instance_method>`
- :ruby-api:`Mongo::Collection#insert_many()<Collection.html#insert_many-instance_method>`
- id: scala
content: |
.. seealso::
- :scala-api:`collection.insertOne()<insertOne(document:TResult,options:org.mongodb.scala.model.InsertOneOptions):org.mongodb.scala.SingleObservable[org.mongodb.scala.Completed]>`
- :scala-api:`collection.insertMany()<insertMany(documents:Seq[_<:TResult],options:org.mongodb.scala.model.InsertManyOptions):org.mongodb.scala.SingleObservable[org.mongodb.scala.Completed]>`
- :ref:`additional-inserts`
- id: csharp
content: |
.. seealso::
- :csharp-api:`IMongoCollection.InsertOne() <M_MongoDB_Driver_IMongoCollection_1_InsertOne>`
- :csharp-api:`IMongoCollection.InsertMany() <M_MongoDB_Driver_IMongoCollection_1_InsertMany>`
- :ref:`additional-inserts`
.. class:: hidden
.. toctree::
:titlesonly:
/reference/insert-methods