Getting Started with MongoDB Atlas

Overview

MongoDB Atlas provides an easy way to host and manage your data inthe cloud. This tutorial guides you through creating an Atlascluster 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 intoAtlas and create your cluster.

Navigate to Atlas to create your Atlas account.

You can register for an account on theMongoDB Atlas landing page.

Once you register, Atlas automatically creates a defaultorganization and project where youcan deploy your first cluster. You can add additional organizationsand projects later.

Once you log in, Atlas prompts you to build your first cluster:

MongoDB Cloud Manager Users

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

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

Deploy a Free Tier Cluster

Estimated completion time: 10 minutes

Atlas Free Tier clusters provide a small-scale developmentenvironment to host your data. Free Tier clusters never expire, andprovide access to a subset of Atlas featuresand functionality.

Paid clusters provide full access to Atlas features, configurationoptions, and operational capabilities. For more information on Paidclusters, including deployment instructions, seeTutorial: Create a New Cluster.

Note

You can deploy only one Free Tier cluster per Atlasproject.

Click Create a Cluster in the left-side panel.

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

Atlas supports M0 Free Tier clusters onAmazon Web Services (AWS),Google Cloud Platform (GCP), andMicrosoft Azure. Regions that supportM0 Free Tier clusters are marked with theFree Tier Available label.

For Cluster Tier, select M0.

Selecting M0 automatically locks the remainingconfiguration options. If you cannot select the M0cluster tier, return to the previous step and select aCloud Provider & Region that supports M0Free Tier clusters.

For Cluster Name, enter GettingStarted.

Click Create Cluster to deploy the cluster.

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

Whitelist Your Connection IP Address

Estimated completion time: 2 minutes

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

To add your IP address to the whitelist:

Open the Connect dialog.

From your Clusters view, click theConnect button for your cluster.

Configure your whitelist entry.

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

Click Add IP Address.

See also

For information on configuring additional whitelist entries inyour 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 securitypurposes, Atlas requires clients to authenticate as MongoDB usersto 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 toMongoDB databases.

To add a MongoDB user to your cluster:

In the same Connect dialog, enter your user information.

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

Note

If your password contains special characters, you will need toencode them. For more information, seeSpecial characters in connection string password.

Click Create MongoDB User.

See also

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

Insert Data into Your Cluster

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

• Atlas GUI
• Mongo Shell
• Driver (Python)

Estimated completion time: 5 minutes

Atlas provides a GUIto interact with data in your cluster, called theData Explorer. You can use theData Explorer to importsample data provided by Atlas intoyour cluster.

To import sample data into your cluster using theData Explorer:

Open the Data Explorer.

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

Click Load a Sample Dataset.

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

The import takes approximately 5 minutes to complete. Once theoperation finishes, the Data Explorer refreshes and youshould 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 thesedatasets, see Available Sample Datasets for Atlas Clusters.

See also

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

View and Edit Your Cluster Data

Estimated completion time: 2 minutes

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

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

Search for a specific document.

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

• Copy the following filter into your filter bar:

{ "title": "Titanic", "year": 1997 }

• Click Find.

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

See also

For more information on querying documents in MongoDB, seeQuery Documents in theMongoDB manual.

Edit the Titanic document.

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

• Hover over the document you filtered for and click thepencil icon icon.

• Hover over the last field in the document and click the appearingplus icon icon.

• Click Add Field After num_mflix_comments.

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

• Click Update to save your changes.

Additional document interactions

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

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

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

Summary

Congratulations! You have just set up an Atlas cluster tohost your data, populated that cluster with sample data, andlearned how to interact with that data using the AtlasData Explorer.

Moving Forward

If you continue to grow your cluster, considerscaling your cluster to support moreusers 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 interactivecommand line interface to MongoDB. You can use the Mongo shellto insert and interact with data on your Atlas cluster.

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

Navigate to your Atlas Clusters view.

Click Clusters in the left navigation pane.

Click your cluster’s Connect button.

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

Click Connect with the Mongo Shell.

Select your operating system.

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

Download the Mongo shell.

• If you are using Windows or Linux, you canchoose to either download the shell directly, or fetch the shellvia URL.
• If you are using macOS, you can use the providedHomebrew command to download the shell.

Add the Mongo shell to your system path.

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

• Windows
• macOS
• Linux

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

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

• Run the following command in your terminal to extractthe Mongo shell:

tar -xzf ./<filename>.tgz

• Add the bin directory to your PATHenvironment variable.

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

Note

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

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

Test your Mongo shell installation.

To see if you have correctly added the Mongo shell to your systempath, 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 theshell to connect to your Atlas cluster.

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

This is a unique connection string specific to your Atlascluster. Atlas replaces the username of the connectionstring with the username of the MongoDB user you created earlierin this procedure.

Paste and run your connection string in your terminal.

When prompted, enter your MongoDB user’s password.

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

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

MongoDB Enterprise GettingStarted-shard-0:PRIMARY>

Connection Troubleshooting

If you are having trouble connecting to your cluster, doublecheck that you have added your IP address to yourIP whitelist and that you are specifyingthe correct MongoDB user credentials. If youhave forgotten your MongoDB user credentials, you can alwayscreate 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 Atlascluster using the Mongo shell, let’s insert a document intoyour cluster.

Switch to a new database called gettingStarted.

In the Mongo shell, run the following command:

use gettingStarted

This command creates a new database calledgettingStarted and points your Mongo shell environment to thatdatabase.

Insert a document into your database.

In the Mongo shell, run the following command to insert a documentinto 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 yourgettingStarted database called people and inserts onedocument into that collection.

You should see the following output, confirming that you havesuccessfully 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 ourcluster.

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

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

When you run this command, you should see the followingoutput:

{
  "_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 forObjectId,because it is a randomly generated value.

See also

For more information on querying data in MongoDB, seeQuery Documents.

Summary

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

Moving Forward

If you continue to grow your cluster, considerscaling your cluster to support moreusers and operations.

Tools Required

To complete this tutorial you must have:

• A terminal.
• Python.
• The pip packageinstaller. This comes prepackaged with the Pythondownload.
• The PyMongo driver.
• A text editor.

Install the PyMongo Driver

Estimated completion time: 5 minutes

MongoDB drivers allow you to communicate with your MongoDBdatabase programatically.

For this tutorial, we will walk through setting up and usingthe Python MongoDB driver, called PyMongo. If youare interested in working with a different driver, refer tothe MongoDB Driver documentation.

Prerequisites

• To install PyMongo, you must have Pythoninstalled. Visit thePython Downloads Pageand download the latest version of Python for youroperating system.
• You will also need thepip packageinstaller. Python 2 >=2.7.9 and Python 3>=3.4 downloaded from https://python.org come withpip already installed. If you need to install pipmanually, refer to the pip installation page forinstructions.

Once you have Python and pip installed:

Open your terminal.

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 fewdependencies for the driver. For more information onthese dependencies, refer to the Python Driver Installation Pageon GitHub.

Test your PyMongo installation.

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

• Run the following command to open the Python shell:

python

• Import PyMongo by running the following command in the Pythonshell:

import pymongo

• Check your PyMongo version using the following command:

pymongo.version

If PyMongo is correctly installed, you should see an outputsimilar 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 fromAtlas to connect to the cluster using the PyMongo driver.

Open your Atlas Clusters view.

Click Clusters at the top-left corner of Atlas.

Click your cluster’s Connect button.

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

Click Connect your Application.

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

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

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

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

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

Import MongoClient from PyMongo.

To connect to a running MongoDB instance, PyMongorequires MongoClient. In the Python shell running in yourterminal, run the followingcommand to import MongoClient:

from pymongo import MongoClient

Connect to your cluster.

In your Python shell, run the following command to specify aclient to connect to your cluster. You will need to paste yourupdated 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 beupdated to contain your MongoDB user password. After you run thiscommand, you will be able to connect to your cluster using thisclient.

Insert Data into Your Atlas Cluster Using the Driver

Estimated completion time: 3 minutes

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

Create a new database on your cluster.

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

db = client.gettingStarted

This command creates a new database on your clustercalled gettingStarted. The variable db points to your newdatabase.

Create a collection for your database.

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

people = db.people

This command creates a new collection in yourgettingStarted database called people. The variablepeople points to your new collection.

Create a new document to insert into your collection.

In your Python shell, run the following command to create a documentwhich 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 thedocument in the next step.

Insert the document into your collection.

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

people.insert_one(personDocument)

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

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

<pymongo.results.InsertOneResult object at 0x10950e5f0>

View Your Cluster Data

Estimated completion time: 1 minute

Now that you have successfully inserted a document intoyour Atlas cluster using the PyMongo driver, you can tryreading that data. You can view your data using theAtlas Data Explorer.

To view your cluster data:

Open the Data Explorer.

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

View your document.

The Data Explorer should display yourgettingStarted.people collection with the document you justinserted:

Note

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

See also

For information on querying data in MongoDB, seeQuery Documents.

Summary

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

Moving Forward

If you continue to grow your cluster, considerscaling your cluster to support moreusers and operations.