Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
450 lines (324 sloc) 15.5 KB
:orphan:
.. _getting-started:
===============
Getting Started
===============
.. default-domain:: mongodb
.. tabs-top::
.. tabs-drivers::
tabs:
- id: shell
content: |
The following tutorial uses the :binary:`~bin.mongo` shell to
insert data and perform query operations.
- id: compass
content: |
`MongoDB Compass <https://docs.mongodb.com/compass/current/>`_
is the GUI for MongoDB. The following tutorial uses MongoDB
Compass to connect to insert data and perform query operations.
- id: python
content: |
The following tutorial uses the
`PyMongo <https://api.mongodb.com/python/current/index.html>`_
Python driver to insert data and perform query operations.
- id: nodejs
content: |
The following tutorial uses the
:node-docs:`MongoDB Node.js Driver <>` to insert data and
perform query operations.
Prerequisites
-------------
This tutorial requires you to be connected to one of the following:
- **MongoDB Atlas Free Tier Cluster**. MongoDB Atlas is a fast, easy, and
free way to get started with MongoDB. Follow the
:ref:`create-free-tier-manual` tutorial to get started with MongoDB
Atlas.
- **Local MongoDB installation**. For more information on installing MongoDB
locally, see :ref:`Install MongoDB<tutorial-installation>`.
Insert Documents
----------------
.. tabs-drivers::
tabs:
- id: shell
content: |
:method:`db.collection.insertMany()` can insert *multiple*
:doc:`documents </core/document>` into a
:doc:`collection</core/databases-and-collections>`. Pass an array of
documents to the method.
The following example inserts new documents into the ``inventory``
collection:
.. class:: copyable-code
.. code-block:: javascript
db.inventory.insertMany([
// MongoDB adds the _id field with an ObjectId if _id is not present
{ item: "journal", qty: 25, status: "A",
size: { h: 14, w: 21, uom: "cm" }, tags: [ "blank", "red" ] },
{ item: "notebook", qty: 50, status: "A",
size: { h: 8.5, w: 11, uom: "in" }, tags: [ "red", "blank" ] },
{ item: "paper", qty: 100, status: "D",
size: { h: 8.5, w: 11, uom: "in" }, tags: [ "red", "blank", "plain" ] },
{ item: "planner", qty: 75, status: "D",
size: { h: 22.85, w: 30, uom: "cm" }, tags: [ "blank", "red" ] },
{ item: "postcard", qty: 45, status: "A",
size: { h: 10, w: 15.25, uom: "cm" }, tags: [ "blue" ] }
]);
: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.
Use :method:`db.collection.insertOne()` to insert a single document.
- id: compass
content: |
1. Click :guilabel:`Create Database`.
.. include:: /images/compass-create-database.rst
2. Enter "retail" for the :guilabel:`Database Name` and
"inventory" for the :guilabel:`Collection Name` then click
:guilabel:`Create Database`. For more information, see
:doc:`/core/databases-and-collections`.
.. include:: /images/compass-create-database-collection.rst
3. From the :guilabel:`Collections` tab, click the "inventory"
collection link.
4. Click the :guilabel:`Insert Document` button.
.. include:: /images/compass-insert-document.rst
5. Insert the following :doc:`document </core/document>` by
entering the ``fields`` and ``values``, then selecting the
appropriate types from the dropdowns. Add fields by clicking
the last line number, then clicking
:guilabel:`Add Field After ...`.
.. code-block:: javascript
{ item: "journal", qty: 25, status: "A",
size: { h: 14, w: 21, uom: "cm" }, tags: [ "blank", "red" ] }
- For ``Object`` types, add nested fields by clicking the last
field's number and selecting :guilabel:`Add Field After ...`.
- For ``Array`` types, add additional elements to the array by
clicking the last element's line number and selecting
:guilabel:`Add Array Element After ...`.
.. include:: /images/compass-insert-document-field.rst
.. include:: /images/compass-insert-document-field-type.rst
6. Repeat steps 4 and 5 to add additional documents:
.. code-block:: javascript
{ item: "notebook", qty: 50, status: "A",
size: { h: 8.5, w: 11, uom: "in" }, tags: [ "red", "blank" ] },
{ item: "paper", qty: 100, status: "D",
size: { h: 8.5, w: 11, uom: "in" }, tags: [ "red", "blank", "plain" ] },
{ item: "planner", qty: 75, status: "D",
size: { h: 22.85, w: 30, uom: "cm" }, tags: [ "blank", "red" ] },
{ item: "postcard", qty: 45, status: "A",
size: { h: 10, w: 15.25, uom: "cm" }, tags: [ "blue" ] }
- id: python
content: |
:py:meth:`pymongo.collection.Collection.insert_many` can insert
*multiple* :doc:`documents </core/document>` into a
:doc:`collection</core/databases-and-collections>`. Pass an array of
documents to the method.
The following example inserts new documents into the ``inventory``
collection:
.. class:: copyable-code
.. code-block:: python
db.inventory.insert_many([
# MongoDB adds the _id field with an ObjectId if _id is not present
{ "item": "journal", "qty": 25, "status": "A",
"size": { "h": 14, "w": 21, "uom": "cm" }, "tags": [ "blank", "red" ] },
{ "item": "notebook", "qty": 50, "status": "A",
"size": { "h": 8.5, "w": 11, "uom": "in" }, "tags": [ "red", "blank" ] },
{ "item": "paper", "qty": 100, "status": "D",
"size": { "h": 8.5, "w": 11, "uom": "in" }, "tags": [ "red", "blank", "plain" ] },
{ "item": "planner", "qty": 75, "status": "D",
"size": { "h": 22.85, "w": 30, "uom": "cm" }, "tags": [ "blank", "red" ] },
{ "item": "postcard", "qty": 45, "status": "A",
"size": { "h": 10, "w": 15.25, "uom": "cm" }, "tags": [ "blue" ] }
])
:py:meth:`~pymongo.collection.Collection.insert_many` returns a
document that includes the newly inserted documents ``_id`` field
values. See the :ref:`reference <insertMany-examples>` for an example.
Use :py:meth:`pymongo.collection.Collection.insert_one` to insert a
single document.
- id: nodejs
content: |
:node-api:`Collection.insertMany() <Collection.html#insertMany>`
can insert *multiple* :doc:`documents </core/document>`
into a :doc:`collection</core/databases-and-collections>`. Pass an
array of documents to the method.
The following example inserts new documents into the
``inventory`` collection:
.. class:: copyable-code
.. code-block:: javascript
db.collection('inventory').insertMany([
// MongoDB adds the _id field with an ObjectId if _id is not present
{ item: "journal", qty: 25, status: "A",
size: { h: 14, w: 21, uom: "cm" }, tags: [ "blank", "red" ] },
{ item: "notebook", qty: 50, status: "A",
size: { h: 8.5, w: 11, uom: "in" }, tags: [ "red", "blank" ] },
{ item: "paper", qty: 100, status: "D",
size: { h: 8.5, w: 11, uom: "in" }, tags: [ "red", "blank", "plain" ] },
{ item: "planner", qty: 75, status: "D",
size: { h: 22.85, w: 30, uom: "cm" }, tags: [ "blank", "red" ] },
{ item: "postcard", qty: 45, status: "A",
size: { h: 10, w: 15.25, uom: "cm" }, tags: [ "blue" ] }
])
.then(function(result) {
// process result
})
:node-api:`insertMany() <Collection.html#insertMany>` returns a
document that includes the newly inserted documents ``_id`` field
values. See the :ref:`reference <insertMany-examples>` for an example.
Use :node-api:`Collection.insertOne() <Collection.html#insertOne>` to
insert a single document.
For more information and examples, see :ref:`Insert Documents<write-op-insert>`
in the :ref:`CRUD<crud>` section.
Query Documents
---------------
Select All Documents
~~~~~~~~~~~~~~~~~~~~
.. tabs-drivers::
tabs:
- id: shell
content: |
To select all documents in the collection, pass an empty document as the
:ref:`query filter document <document-query-filter>` to the
:method:`db.collection.find()` method:
- id: compass
content: |
Select the ``inventory`` collection from the :guilabel:`Collections`
tab or the left-hand pane. By default, all documents are selected and
additional documents are loaded by scrolling down.
To explicitly select all documents in the collection, pass an empty
:ref:`query filter document <document-query-filter>` ``{ }`` to
the :guilabel:`Filter` input and click :guilabel:`Find`.
.. include:: /images/compass-find-all.rst
- id: python
content: |
To select all documents in the collection, pass an empty document as the
:ref:`query filter document <document-query-filter>` to the
:py:meth:`pymongo.collection.Collection.find` method:
- id: nodejs
content: |
To select all documents in the collection, pass an empty document as the
:ref:`query filter document <document-query-filter>` to the
:node-api:`Collection.find() <Collection.html#find>` method:
.. include:: /includes/driver-examples/driver-example-query-7.rst
.. tabs-drivers::
tabs:
- id: shell
content: |
To query for documents that match specific equality conditions, pass the
:method:`~db.collection.find()` method a :ref:`query filter document <document-query-filter>`
with the ``<field>: <value>`` of the desired documents. The following example
selects from the ``inventory`` collection all documents where the ``status``
equals ``"D"``:
- id: compass
content: |
To query for documents that match specific equality conditions, pass
a :ref:`query filter document <document-query-filter>` to the
:guilabel:`Filter` with the ``<field>: <value>`` of the desired
documents. The following query filter document selects all documents
where the ``status`` equals ``"D"`` from the ``inventory`` collection:
.. class:: copyable-code
.. code-block:: javascript
{ status: "D" }
.. include:: /images/compass-find-filter.rst
- id: python
content: |
To query for documents that match specific equality conditions, pass the
:py:meth:`~pymongo.collection.Collection.find` method a
:ref:`query filter document <document-query-filter>` with the
``<field>: <value>`` of the desired documents. The following example
selects from the ``inventory`` collection all documents where the
``status`` equals ``"D"``:
- id: nodejs
content: |
To query for documents that match specific equality conditions, pass the
:node-api:`find() <Collection.html#find>` method a
:ref:`query filter document <document-query-filter>` with the
``<field>: <value>`` of the desired documents. The following example
selects from the ``inventory`` collection all documents where the
``status`` equals ``"D"``:
.. include:: /includes/driver-examples/driver-example-query-9.rst
Match an Embedded Document
~~~~~~~~~~~~~~~~~~~~~~~~~~
Equality matches on the whole embedded document require an *exact*
match of the specified ``<value>`` document, including the field order. For
example, the following query selects all documents where the field ``size``
equals the document ``{ h: 14, w: 21, uom: "cm" }``:
.. include:: /includes/driver-examples/driver-example-query-15.rst
.. tabs-drivers::
tabs:
- id: compass
content: |
.. class:: copyable-code
.. code-block:: javascript
{ size: { h: 14, w: 21, uom: "cm" } }
.. include:: /images/compass-find-embedded.rst
Match a Field in an Embedded Document
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following example selects all documents where the field ``uom``
nested in the ``size`` field equals the string value ``"in"``:
.. include:: /includes/driver-examples/driver-example-query-17.rst
.. tabs-drivers::
tabs:
- id: compass
content: |
.. class:: copyable-code
.. code-block:: javascript
{ "size.uom": "in" }
.. include:: /images/compass-find-embedded-field.rst
Match an Element in an Array
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following example queries for all documents where ``tags`` is an
array that contains the string ``"red"`` as one of its elements:
.. include:: /includes/driver-examples/driver-example-query-23.rst
.. tabs-drivers::
tabs:
- id: compass
content: |
.. class:: copyable-code
.. code-block:: javascript
{ tags: "red" }
.. include:: /images/compass-find-array-element.rst
Match an Array Exactly
~~~~~~~~~~~~~~~~~~~~~~
The following example queries for all documents where the field ``tags``
value is an array with exactly two elements, ``"red"`` and ``"blank"``,
in the specified order:
.. include:: /includes/driver-examples/driver-example-query-21.rst
.. tabs-drivers::
tabs:
- id: compass
content: |
.. class:: copyable-code
.. code-block:: javascript
{ tags: ["red", "blank"] }
.. include:: /images/compass-find-array-exact.rst
For more information and query examples, see
:ref:`Query Documents<read-operations-queries>` in the :ref:`CRUD<crud>`
section.
To update or delete documents, see :ref:`Update Documents<write-op-update>` and
:ref:`Delete Documents<write-op-delete>`.
Next Steps
----------
Once you complete the Getting Started Guide, you may find the following course
and topics useful:
To learn more about the MongoDB query language and other MongoDB fundamentals,
sign up for `M001: MongoDB Basics <https://university.mongodb.com/courses/M001/about>`_.
.. list-table::
:header-rows: 1
:class: index-table
* - Introduction
- Developers
- Administrators
- Reference
* - :doc:`/introduction`
:doc:`Installation Guides </installation>`
:doc:`/core/databases-and-collections`
:doc:`/core/document`
- :doc:`CRUD Operations </crud>`
:doc:`Aggregation </aggregation>`
:doc:`SQL to MongoDB </reference/sql-comparison>`
:doc:`/indexes`
- :doc:`/administration/production-notes`
:doc:`Replica Sets </replication>`
:doc:`Sharded Clusters </sharding>`
:doc:`MongoDB Security </security>`
- :doc:`Shell Methods </reference/method>`
:doc:`Query Operators </reference/operator>`
:doc:`Reference </reference>`
:doc:`/reference/glossary`
You can’t perform that action at this time.