Navigation

Getting Started with MongoDB Atlas

Overview

MongoDB Atlas provides an easy way to host and manage your data in the cloud. This tutorial guides you through creating an Atlas cluster and populating that cluster with data.

Create an Atlas Account

Estimated completion time: 5 minutes

You will need to register an Atlas account to log into Atlas and create your cluster.

1

MongoDB Cloud Manager Users

If you are an existing MongoDB Cloud Manager user, you can use your Cloud Manager credentials to log in to Atlas. You can then create a new Atlas project from Cloud Manager.

Once you have created your Atlas project, you can move on to the next section.

Deploy a Free Tier Cluster

Estimated completion time: 10 minutes

Atlas Free Tier clusters provide a small-scale development environment to host your data. Free Tier clusters never expire, and provide access to a subset of Atlas features and functionality.

Paid clusters provide full access to Atlas features, configuration options, and operational capabilities. For more information on Paid clusters, including deployment instructions, see Tutorial: Create a New Cluster.

Note

You can deploy only one Free Tier cluster per Atlas project.

1

For Cloud Provider & Region, select your preferred Cloud Provider.

Atlas supports M0 Free Tier clusters on Amazon Web Services (AWS), Google Cloud Platform (GCP), and Microsoft Azure. Regions that support M0 Free Tier clusters are marked with the Free Tier Available label.

Image highlighting Free Tier clusters
2

For Cluster Tier, select M0.

Selecting M0 automatically locks the remaining configuration options. If you cannot select the M0 cluster tier, return to the previous step and select a Cloud Provider & Region that supports M0 Free Tier clusters.

3

For Cluster Name, enter GettingStarted.

4

Click Create Cluster to deploy the cluster.

Once you deploy your cluster, it can take up to 10 minutes for your cluster to provision and become ready to use.

Whitelist Your Connection IP Address

Estimated completion time: 2 minutes

An IP address is a unique numeric identifier for a device connecting to a network. Within Atlas, you can create a list of trusted IP addresses that can connect to your cluster and access your data. Atlas only allows connections to a cluster from addresses listed in the IP whitelist.

To add your IP address to the whitelist:

1

Open the Connect dialog.

From your Clusters view, click the Connect button for your cluster.

Screenshot highlighting cluster connect button.
2

Configure your whitelist entry.

In the Whitelist your connection IP address step, click Add Your Current IP Address.

3

Click Add IP Address.


Screeenshot of adding a new whitelist entry.

See also

For information on configuring additional whitelist entries in your project, see Configure Whitelist Entries.

Create a MongoDB User for Your Cluster

Estimated completion time: 2 minutes

You must create a MongoDB user to access your deployment. For security purposes, Atlas requires clients to authenticate as MongoDB users to access clusters.

MongoDB users are separate from Atlas users:

  • MongoDB users can access databases hosted in Atlas.
  • Atlas users can log into Atlas but do not have access to MongoDB databases.

To add a MongoDB user to your cluster:

1

In the same Connect dialog, enter your user information.

  1. In the Create a MongoDB User step of the dialog, enter a Username for your MongoDB user. For this tutorial, we’ll use MyMongoDBUser as an example username.
  2. Enter a Password for your user. You’ll use this username and password combination to access data on your cluster.

Screeenshot of adding a new user.

Note

If your password contains special characters, you will need to encode them. For more information, see Special characters in connection string password.

2

Click Create MongoDB User.

See also

For information on configuring additional MongoDB users on your cluster, see Configure MongoDB Users.

Insert Data into Your Cluster

The following steps in this tutorial show you how to insert and interact with data on your cluster. Select the appropriate tab based on how you would like to interact with your cluster data:

Estimated completion time: 5 minutes

Atlas provides a GUI to interact with data in your cluster, called the Data Explorer. You can use the Data Explorer to import sample data provided by Atlas into your cluster.

To import sample data into your cluster using the Data Explorer:

1

Open the Data Explorer.

From the Atlas Clusters view, click your cluster’s Collections button.

Screenshot highlighting cluster collections button.
2

Click Load a Sample Dataset.

Image showing the initial Data Explorer screen
3

In the ensuing dialog, click Load Sample Dataset to confirm.

The import takes approximately 5 minutes to complete. Once the operation finishes, the Data Explorer refreshes and you should see the following five databases in your cluster:

  • sample_airbnb
  • sample_geospatial
  • sample_mflix
  • sample_training
  • sample_weatherdata

For details on the collections and documents included in these datasets, see Available Sample Datasets.

See also

For more information on Data Explorer in Atlas, see Data Explorer.

View and Edit Your Cluster Data

Estimated completion time: 2 minutes

Now that you have imported some data into your cluster, you can try viewing and modifying it.

1

In the Data Explorer, open the sample_mflix database and select the movies collection.

Image showing the sample.mflix database
2

Search for a specific document.

You can use the Data Explorer’s Filter bar to search for specific documents. The following query filters the documents in the sample_mflix.movies collection for movies with the title Titanic and the year 1997.

  1. Copy the following filter into your filter bar:

    { "title": "Titanic", "year": 1997 }
    
  2. Click Find.


    Image showing filter in Data Explorer

    The Data Explorer should return a single document after you apply this filter.

See also

For more information on querying documents in MongoDB, see Query Documents in the MongoDB manual.

3

Edit the Titanic document.

Now that you have located a specific document in the collection, you can try modifying it.

  1. Hover over the document you filtered for and click the pencil icon icon.



    Image showing how to open the edit document dialog


  2. Hover over the last field in the document and click the appearing plus icon icon.

  3. Click Add Field After num_mflix_comments.



    Image showing adding a new field in edit view.

  4. Create a new field with a key named review. For the value, enter a brief review of the movie. Leave your field’s data type as the default String.



    Image showing adding the review field in edit view.

  5. Click Update to save your changes.

Additional document interactions

You can also use the Data Explorer to interact with your documents in the following ways:

  • Copy documents to your system clipboard
  • Clone documents
  • Delete documents

To perform these operations, hover over your desired document and select the appropriate action.

Summary

Congratulations! You have just set up an Atlas cluster to host your data, populated that cluster with sample data, and learned how to interact with that data using the Atlas Data Explorer.

Moving Forward

If you continue to grow your cluster, consider scaling your cluster to support more users and operations.

Tools Required

To complete this tutorial you must have:

  • A terminal
  • The Mongo shell

Download and Install the Mongo Shell

Estimated completion time: 5 minutes

The Mongo shell is an interactive command line interface to MongoDB. You can use the Mongo shell to insert and interact with data on your Atlas cluster.

Atlas provides an easy way to download and install the Mongo shell. To download and install the Mongo shell:

1
2

Click your cluster’s Connect button.

You completed the Setup connection security step in a previous section of this tutorial. You should now be on the Choose a connection method step in the dialog.

Image highlighting the Choose Connection Method step
3

Click Connect with the Mongo Shell.

4

Select your operating system.

Select your operating system from the dropdown in step 1 of the dialog.

5

Download the Mongo shell.

  • If you are using Windows or Linux, you can choose to either download the shell directly, or fetch the shell via URL.
  • If you are using macOS, you can use the provided Homebrew command to download the shell.
6

Add the Mongo shell to your system path.

To run the Mongo shell from your terminal, you will need to add the shell to your system path. Select the appropriate tab based on your operating system:

  1. Double-click the .msi file in Windows Explorer and proceed through the installation wizard.
  2. Add the bin directory to your command path.
    1. Click windows icon and select Control Panel.
    2. Click System and Security, then System, then Advanced System Settings.
    3. Click Environment Variables.
    4. Select Path and click Edit.
    5. Add the bin directory where the installer placed your MongoDB executables and click OK.

Copy the Homebrew command from the Atlas UI window and run it in your terminal.

  1. Run the following command in your terminal to extract the Mongo shell:

    tar -xzf ./<filename>.tgz
    
  2. Add the bin directory to your PATH environment variable.

    export PATH=/<extraction-directory>/bin:$PATH
    

    Note

    This command applies only to the current shell session. Edit the PATH environment variable in ~/.profile to update the variable across shell sessions and reboots.

You should now be able to run the Mongo shell using your terminal.

7

Test your Mongo shell installation.

To see if you have correctly added the Mongo shell to your system path, run the following command in your terminal:

mongo --version

You should see an output similar to the following:

MongoDB shell version v4.0.7
git version: 7c13a75b928ace3f65c9553352689dc0a6d0ca83
allocator: system
modules: none
build environment:
    distarch: x86_64
    target_arch: x86_64

Connect to Your Cluster Using the Mongo Shell

Estimated completion time: 3 minutes

Now that you have installed the Mongo shell, you can use the shell to connect to your Atlas cluster.

1

From the same Connect dialog, copy the provided connection string to your clipboard.

Image highlighting sample copyable connection string.

This is a unique connection string specific to your Atlas cluster. Atlas replaces the username of the connection string with the username of the MongoDB user you created earlier in this procedure.

2

Paste and run your connection string in your terminal.

3

When prompted, enter your MongoDB user’s password.

You will be prompted to enter the password you specified when you created your MongoDB user in Atlas.

You should now be connected to your Atlas cluster within the Mongo shell. Your terminal should display something similar to the following:

MongoDB Enterprise GettingStarted-shard-0:PRIMARY>

Connection Troubleshooting

If you are having trouble connecting to your cluster, double check that you have added your IP address to your IP whitelist and that you are specifying the correct MongoDB user credentials. If you have forgotten your MongoDB user credentials, you can always create a new MongoDB user.

Insert Data Into Your Cluster Using the Mongo Shell

Estimated completion time: 1 minute

Now that you have successfully connected to your Atlas cluster using the Mongo shell, let’s insert a document into your cluster.

1

Switch to a new database called gettingStarted.

In the Mongo shell, run the following command:

use gettingStarted

This command creates a new database called gettingStarted and points your Mongo shell environment to that database.

2

Insert a document into your database.

In the Mongo shell, run the following command to insert a document into your new database:

db.people.insert({
  name: { first: "Alan", last: "Turing" },
  birth: new Date('Jun 23, 1912'),
  death: new Date('Jun 07, 1954'),
  contribs: [ "Turing machine", "Turing test", "Turingery" ],
  views : NumberLong(1250000)
})

This command creates a new collection in your gettingStarted database called people and inserts one document into that collection.

You should see the following output, confirming that you have successfully inserted a document into your collection:

WriteResult({ "nInserted" : 1 })

View Data Using the Mongo Shell

Estimated completion time: 1 minute

Now we can try reading the data we just inserted into our cluster.

The following command searches our people collection for documents which have a name.last value of Turing:

db.people.find({ "name.last": "Turing" })

When you run this command, you should see the following output:

{
  "_id" : ObjectId("5c9bca3c5345268c98ac7abc"),
  "name" : {
    "first" : "Alan",
    "last" : "Turing"
  },
  "birth" : ISODate("1912-06-23T04:00:00Z"),
  "death" : ISODate("1954-06-07T04:00:00Z"),
  "contribs" : [
    "Turing machine",
    "Turing test",
    "Turingery"
  ],
  "views" : NumberLong(1250000)
}

Note

You may see a different value for ObjectId, because it is a randomly generated value.

See also

For more information on querying data in MongoDB, see Query Documents.

Summary

Congratulations! You’ve just set up an Atlas cluster to host your data, and used the Mongo shell to write and read data to and from your cluster.

Moving Forward

If you continue to grow your cluster, consider scaling your cluster to support more users and operations.

Tools Required

To complete this tutorial you must have:

  • A terminal.
  • Python.
  • The pip package installer. This comes prepackaged with the Python download.
  • The PyMongo driver.
  • A text editor.

Install the PyMongo Driver

Estimated completion time: 5 minutes

MongoDB drivers allow you to communicate with your MongoDB database programatically.

For this tutorial, we will walk through setting up and using the Python MongoDB driver, called PyMongo. If you are interested in working with a different driver, refer to the MongoDB Driver documentation.

Prerequisites

  • To install PyMongo, you must have Python installed. Visit the Python Downloads Page and download the latest version of Python for your operating system.
  • You will also need the pip package installer. Python 2 >=2.7.9 and Python 3 >=3.4 downloaded from https://python.org come with pip already installed. If you need to install pip manually, refer to the pip installation page for instructions.

Once you have Python and pip installed:

1

Open your terminal.

2

Install the PyMongo Driver.

Run the following command in your terminal:

python -m pip install pymongo[snappy,gssapi,srv,tls]

This command installs the PyMongo driver and as well as a few dependencies for the driver. For more information on these dependencies, refer to the Python Driver Installation Page on GitHub.

3

Test your PyMongo installation.

Let’s test your PyMongo installation to make sure you can successfully connect to your cluster.

  1. Run the following command to open the Python shell:

    python
    
  2. Import PyMongo by running the following command in the Python shell:

    import pymongo
    
  3. Check your PyMongo version using the following command:

    pymongo.version
    

    If PyMongo is correctly installed, you should see an output similar to the following:

    '3.4.0'
    

Connect to Your Atlas Cluster Using the Driver

Estimated completion time: 5 minutes

You’ll need to get your cluster’s connection string from Atlas to connect to the cluster using the PyMongo driver.

1

Open your Atlas Clusters view.

Click Clusters at the top-left corner of Atlas.

2

Click your cluster’s Connect button.

You completed the Setup connection security step in a previous section of this tutorial. You should now be on the Choose a connection method step in the dialog.

Image highlighting the Choose Connection Method step
3

Click Connect your Application.

4

Select Python from the Driver dropdown and select your version of the driver.

5

Copy the provided connection string from the Connection String Only dialog tab.

Image showing the connection string example
6

In a text editor, update the copied connection string with your password.

For security purposes, Atlas does not show your MongoDB user’s password in the connection string. Instead, your connection string has a placeholder <password>.

Open your preferred text editor and paste the connection string that you copied from Atlas. Replace <password> with the password you specified when you created your MongoDB user.

7

Import MongoClient from PyMongo.

To connect to a running MongoDB instance, PyMongo requires MongoClient. In the Python shell running in your terminal, run the following command to import MongoClient:

from pymongo import MongoClient
8

Connect to your cluser.

In your Python shell, run the following command to specify a client to connect to your cluster. You will need to paste your updated connection string from your text editor into this command:

client = MongoClient('<your updated connection string>')

Your connection string should be in single quotes, and should be updated to contain your MongoDB user password. After you run this command, you will be able to connect to your cluster using this client.

Insert Data into Your Atlas Cluster Using the Driver

Estimated completion time: 3 minutes

Now that you have established a client to connect to your cluster, you can create a database and a collection on your cluster and insert some data.

1

Create a new database on your cluster.

We have already established our client connection and stored it in a variable called client. Run the following command in your Python shell to create a database on your cluster:

db = client.gettingStarted

This command creates a new database on your cluster called gettingStarted. The variable db points to your new database.

2

Create a collection for your database.

Run the following command in your Python shell to create a new collection for your database:

people = db.people

This command creates a new collection in your gettingStarted database called people. The variable people points to your new collection.

3

Create a new document to insert into your collection.

In your Python shell, run the following command to create a document which will be inserted into your collection:

import datetime
personDocument = {
  "name": { "first": "Alan", "last": "Turing" },
  "birth": datetime.datetime(1912, 6, 23),
  "death": datetime.datetime(1954, 6, 7),
  "contribs": [ "Turing machine", "Turing test", "Turingery" ],
  "views": 1250000
}

The document is stored in a variable called personDocument.

Note

This command does not insert the document into your collection. This command only specifies the document. We will insert the document in the next step.

4

Insert the document into your collection.

In your Python shell, run the following command to insert the document you created in the previous step into your collection:

people.insert_one(personDocument)

Remember that the people variable refers to our people collection we specified in a previous step of this section, and personDocument contains the document we want to insert.

If your insert was successful, PyMongo displays a message similar to the following:

<pymongo.results.InsertOneResult object at 0x10950e5f0>

View Your Cluster Data

Estimated completion time: 1 minute

Now that you have successfully inserted a document into your Atlas cluster using the PyMongo driver, you can try reading that data. You can view your data using the Atlas Data Explorer.

To view your cluster data:

1

Open the Data Explorer.

From the Atlas Clusters view, click your cluster’s Collections button.

Screenshot highlighting cluster collections button.
2

View your document.

The Data Explorer should display your gettingStarted.people collection with the document you just inserted:

Screenshot showing Data Explorer with single document

Note

You may see a different value for ObjectId, because it is a randomly generated value.

See also

For information on querying data in MongoDB, see Query Documents.

Summary

Congratulations! You’ve just set up an Atlas cluster to host your data and used the PyMongo driver to write and read data to and from your cluster.

Moving Forward

If you continue to grow your cluster, consider scaling your cluster to support more users and operations.