Navigation

Getting Started

This procedure guides you through creating and configuring an Atlas cluster, populating the cluster with data, and modifying that data.

A. Create an Atlas User Account

Estimated completion time: 5 minutes

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.

In Cloud Manager, click on the Context drop down and select New Project. In the Create new Project,select MongoDB Atlas and continue with creating the project.

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

Go to Atlas to create your user account. As a part of creating an Atlas user, Atlas automatically creates a default organization and project for you to deploy your first cluster into. You can add additional organizations and projects later.

Creating a user for Atlas also creates that user on jira.mongodb.org. If you later change the user’s password or email address in Atlas, you will also change the password or email address in jira.mongodb.org.

Once you log in, the Atlas UI automatically opens the cluster creation dialog.

B. Create an Atlas Free Tier Cluster

Estimated completion time: 10 minutes

Atlas Free Tier clusters are an ideal development sandbox, providing access to a subset of Atlas features and functionality. You can deploy only one Free Tier cluster per Atlas project.

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

1

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

Atlas supports M0 Free Tier clusters on Amazon Web Services (AWS), Google Cloud Project (GCP), and Microsoft Azure. Atlas marks cloud provider regions that support M0 Free Tier clusters with the Free Tier Available label.

Cloud Provider Supported Regions
AWS
  • N. Virginia (us-east-1)
  • Frankfurt (eu-central-1)
  • Singapore (ap-southeast-1)
  • Mumbai (ap-south-1)
GCP
  • Iowa (us-central-1)
  • Belgium (europe-west-1)
  • Singapore (asia-southeast1)
Azure
  • Virginia (eastus2)
  • Netherlands (westeurope)
  • Hong Kong (eastasia)
2

For Cluster Tier, select M0.

Selecting M0 automatically locks the remaining configuration options. If you cannot select the M0 instance size, 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 Deploy to deploy the cluster.

5

Configure Security for your Project.

Atlas only allows client connections to the cluster from entries in the project IP whitelist. Clients must also authenticate as a MongoDB database user associated to the project.

If you have not configured the project IP whitelist or MongoDB users, follow the prompts in the Atlas Clusters view to configure basic project security.

When creating your first MongoDB database user, select the Atlas admin role from the user configuration dialog to create an administrative user. See MongoDB Database User Privileges for more information on MongoDB user privileges.

If you need to modify your existing project security settings, click the Security tab from the Clusters view. See Security Features and Setup for complete documentation on Atlas project security settings.

6

Optional: Connect to and test your Free Tier cluster.

Once Atlas finishes creating your Free Tier cluster, click the Connect button for the cluster. From the Connect dialog, do the following:

  1. Check that the IP address of the client you want to connect from is included under Check the IP Whitelist. You can add your current IP address to the Project IP Whitelist by clicking Add Current IP Address.

    If you want to connect from a different machine, click Add Entry and input the specific IP address for that machine.

  2. Select Connect with the Mongo Shell.

    The Connect dialog displays operating system-specific instructions for downloading the mongo shell. Follow the instructions in the Connect dialog to download and install the shell.

  3. Connect with the mongo shell by following the remaining instructions in the Connect dialog. You will need the password for the administrative user you created when configuring the Free Tier cluster.

  4. Insert a document into the test.foo collection:

    db.getSiblingDB("test").getCollection("foo").insert( { "msg" : "My First Document" } )
    
  5. Find all documents in the test.foo collection:

    db.getSiblingDB("test").getCollection("foo").find()
    

Once you have confirmed your cluster is available and accessible, continue to the following section.

C. (Tutorial) Import Data to your Free Tier Cluster

Estimated completion time: 5 minutes

1

Open the Command Line Tools tab.

To access the Atlas Command Line Tools tab:

  1. From the Atlas UI, use the Context picker in the top-left hand corner to select the Atlas project associated to the cluster you want to connect to.
  2. Click ellipsis h icon for the cluster. From this menu, click Command Line Tools.

You can also click on the cluster in the Atlas UI and select the Command Line Tools tab from the cluster view.

2

Retrieve and modify the mongoimport connection template.

The Data Import and Export Tools section of the Command Line Tools tab displays a copyable template with the minimum required options for connecting mongoimport to your Atlas cluster.

The template includes placeholder values for certain options. Copy and paste the template into your preferred text editor and make the following modifications:

Variable Description
<USERNAME> and <PASSWORD> Replace with the password for the user specified in --username. The template includes a MongoDB user for the project as the --username. If you want to authenticate as a different user, replace the value of --username and specify the password for that user in --password.
<DATABASE> Replace with guidebook
<COLLECTION> Replace with restaurants
<FILETYPE> Replace with json
<FILENAME> Replace with the path to primer-dataset.json.

Your command should resemble the following:

mongoimport \
  --host example/00.example.net:27017,01.example.net:27017,02.example.net:27017 \
  --ssl --username <USERNAME> --password <PASSWORD> \
  --authenticationDatabase admin \
  --db guidebook --collection restaurants \
  --type json
3

Load the primer dataset.

To load the dataset, you can either:

Download, then Import:

You can download the dataset from GitHub.

wget https://raw.githubusercontent.com/mongodb/docs-assets/primer-dataset/primer-dataset.json

Run mongoimport in the shell on the downloaded file.

mongoimport --host RKDevTest-shard-0/rkdevtest-shard-00-00-zax0p.mongodb-dev.net:27017,rkdevtest-shard-00-01-zax0p.mongodb-dev.net:27017,rkdevtest-shard-00-02-zax0p.mongodb-dev.net:27017 \
  --ssl --username <USERNAME> --password <PASSWORD> \
  --authenticationDatabase admin --db guidebook \
  --collection restaurants --type json \
  --file primer-dataset.json
Download and import:

Download and import the dataset as one command in your shell:

wget -q -O- https://raw.githubusercontent.com/mongodb/docs-assets/primer-dataset/primer-dataset.json | \
mongoimport --host RKDevTest-shard-0/rkdevtest-shard-00-00-zax0p.mongodb-dev.net:27017,rkdevtest-shard-00-01-zax0p.mongodb-dev.net:27017,rkdevtest-shard-00-02-zax0p.mongodb-dev.net:27017 \
  --ssl --username <USERNAME> --password <PASSWORD> \
  --authenticationDatabase admin --db guidebook \
  --collection restaurants --type json

Omit the --file option when using this method.

Important

Ensure that the host where you are running mongoimport is in the project IP whitelist.

To review your project whitelist, click Security from the Atlas projects view, then click IP Whitelist. For complete documentation on managing your project whitelist, see Project IP Whitelist.

For more information on importing data into Atlas, see Import Data into Cluster.

D. Modify Data in your Free Tier Cluster

Estimated completion time: 15 minutes

1

Connect to your Free Tier Cluster.

  1. From the Clusters view, click Connect for the Free Tier cluster.

  2. For Connect with the Mongo Shell, click Select Operating System and select your operating system.

  3. Click Copy to copy the full shell command.

  4. Paste the shell command into your operating system shell or terminal:

    mongo "mongodb://mongo1.example.net:27017,mongo2.example.net:27017,mongo3.example.net:27017/test?replicaSet=AtlasReplicaSet" \
      --authenticationDatabase admin --ssl \
      --username adminUsername --password <PASSWORD>
    
  5. Replace the <PASSWORD> placeholder with the password for your administrative user.

  6. Execute the shell command to connect to your cluster. The mongo shell should run and display GettingStarted-PRIMARY> in the mongo shell prompt - this indicates a successfull connection.

  7. Enter use guidebook into the prompt and execute to change the active database to guidebook.

  8. Enter show collections into the prompt and execute to display the collections in the database. You should see the restaurants collection.

If the connection fails, double check that:

  • The <PASSWORD> entered is correct,
  • The machine you are connecting from is whitelisted, and
  • The mongo shell version is 3.4.7 or greater and supports TLS/SSL. You can check by running mongo --version.
2

Query the guidebook.restaurants collection.

From the mongo shell, use db.collection.find() to query for documents.

db.restaurants.find()

This operation returns output similar to the following:

{
  "_id" : ObjectId("5977a0cb705246a689e91a6d"),
  "address" : {
    "building" : "469",
    "coord" : [
      -73.961704,
      40.662942
    ],
    "street" : "Flatbush Avenue",
    "zipcode" : "11225"
  },
  "borough" : "Brooklyn",
  "cuisine" : "Hamburgers",
  "grades" : [
    {
      "date" : ISODate("2014-12-30T00:00:00Z"),
      "grade" : "A",
      "score" : 8
    },
    {
      "date" : ISODate("2014-07-01T00:00:00Z"),
      "grade" : "B",
      "score" : 23
    },
    {
      "date" : ISODate("2013-04-30T00:00:00Z"),
      "grade" : "A",
      "score" : 12
    },
    {
      "date" : ISODate("2012-05-08T00:00:00Z"),
      "grade" : "A",
      "score" : 12
    }
  ],
  "name" : "Wendy'S",
  "restaurant_id" : "30112340"
}

The following operation queries for all documents in the borough of Manhattan, using the $slice operator to project only the first element in the grades array.

db.restaurants.find( { "borough" : "Manhattan" } , { "grades" : { $slice : 1 } } )

This operation returns output similar to the following:

{
  "_id" : ObjectId("5977a0cb705246a689e91aa8"),
  "address" : {
    "building" : "837",
    "coord" : [
      -73.9712,
      40.751703
    ],
    "street" : "2 Avenue",
    "zipcode" : "10017"
  },
  "borough" : "Manhattan",
  "cuisine" : "American",
  "grades" : [
    {
      "date" : ISODate("2014-07-22T00:00:00Z"),
      "grade" : "B",
      "score" : 19
    }
  ],
  "name" : "Palm Restaurant",
  "restaurant_id" : "40364355"
}

For detailed documentation on CRUD operations using the MongoDB shell, see the Getting Started Guide.

3

Use Aggregation to Count the Number of Letter Grades per Borough.

From the mongo shell, use db.collection.aggregate() to perform aggregation operations.

db.restaurants.aggregate(
   [
      { $unwind : "$grades" },
      { $group : {
         _id :
            { "borough" : "$borough" , "grade" : "$grades.grade" },
         count : { $sum : 1} }
         },
      { $group : {
         _id : "$_id.borough",
         "grades" : {
            $push : {
               grade : "$_id.grade", count : "$count"
               }
            }
         }
      }
   ]
)

This aggregation operation works as follows:

  1. $unwind deconstructs the grades array from each input document to output one document for each element in the array. The output document structure of this stage is similar to the following:

    {
      "_id" : ObjectId("5977a0cb705246a689e91aa8"),
      ...,
      "borough" : "Manhattan",
      "grades" : {
        "date" : ISODate("2014-07-22T00:00:00Z"),
        "grade" : "B",
        "score" : 19
      }
    }
    
  2. $group groups input documents by the borough and grade fields, using the $sum accumulator to increment the count field for each occurance of a given combination of borough and grade. The output document structure of this stage is as follows:

    { _id : {"borough" : <string> , "grade" : <string> }, count : <int> }
    
  3. $group groups input documents by _id.borough, using the $push operator to push each value of _id.grade and count to the grade array.

This operation returns output similar to the following:

{
  "_id" : "Brooklyn",
  "grades" : [
    {
      "grade" : "Not Yet Graded",
      "count" : 145
    },
    {
      "grade" : "Z",
      "count" : 285
    },
    {
      "grade" : "C",
      "count" : 811
    },
    {
      "grade" : "A",
      "count" : 17324
    },
    {
      "grade" : "B",
      "count" : 3055
    },
    {
      "grade" : "P",
      "count" : 343
    }
  ]
}

For detailed documentation on CRUD operations using the MongoDB shell, see the Aggregation section of the Getting Started Guide.