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. 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 cloud.mongodb.com 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 Cluster Name, enter GettingStarted.

2

For Instance Size, select M0.

Selecting M0 automatically locks the remaining configuration options.

If you do not see the M0 instance size, ensure that the Cloud Provider and Region dropdowns have Amazon Web Services and either N. Virginia (us-east-1) or Frankfurt (eu-central-1) selected.

3

Create an administrative Username and Password.

Atlas prompts you to create an administrative MongoDB user as a part of deploying the first Atlas cluster in the project. This user has administrative access to any MongoDB cluster you deploy in the Atlas project.

Fill in the username and password fields. The password should be random, long, and complex to ensure system security and to impede malicious access.

For more information on Atlas user security, see Add MongoDB Users.

4

Click Deploy to deploy the cluster.

5

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. Add your current IP address to the Group IP Whitelist by clicking Add Current IP Address. This allows you to connect to the cluster from your current machine.

    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 Connect Dialog for the Free Tier Cluster

Go to the Clusters view. Click the Connect button for the Free Tier cluster you created for this procedure.

The Connect dialog provides instructions for configuring the group whitelist to allow access to your cluster, as well as providing the URI connection string for connecting to the cluster.

2

Configure IP Whitelisting to Grant Access To Your Cluster.

Atlas only allows client connections to the cluster from entries in the group’s whitelist.

Atlas displays any entries already on the group whitelist in the Connect dialog under Check the IP Whitelist. If you do not see the IP address of your client on the list, you can:

  • Click Add Entry to add a single IP address or a CIDR-notated range of addresses.

    For Atlas clusters deployed on Amazon Web Services and using VPC Peering, you can add a Security Group associated with the peer VPC.

  • Click Add Current IP Address to add your current IP address.

  • Click Allow Access From Anywhere to allow access from any IP address.

    Warning

    Using Allow Access From Anywhere results in all clusters in the Atlas group being publically accessible. Consider the security risks of having public-facing MongoDB clusters before using this option.

3

Retrieve the Free Tier Cluster Host String.

From the Connect dialog:

  1. Click Connect Your Application.
  2. Copy the URI Connection String.
  3. Paste the URI connection string into a text editor.
  4. Replace the <PASSWORD> with the password for the MongoDB user.
  5. Replace <DATABASE> with guidebook.
  6. Copy the updated URI connection string.
4

Run mongoimport.

mongoimport 3.4.7 adds support for a MongoDB URI connection string via the --uri option. Go to the MongoDB Download Center to download MongoDB Server 3.4.7 or later. The server package includes mongoimport. For Windows and OSX users, you must download the MongoDB package with SSL support.

The following operation imports data from primer-dataset.json into the restaurants collection in the guidebook database. It uses the --uri option along with the modified URI connection string from the previous step to connect to the Free Tier cluster.

wget -qO- https://raw.githubusercontent.com/mongodb/docs-assets/primer-dataset/primer-dataset.json |
  mongoimport --collection "restaurants" \
  --uri "mongodb://admin:mysecretpassword@mongo1.example.net:27017,mongo2.example.net:27017,mongo3.example.net:27017/guidebook?ssl=true&replicaSet=GettingStarted&authSource=admin" \
  primer-dataset.json

Alternatively, you can enter in the cluster connection details manually. From the Connect dialog, click Connect Your Application, then Copy to copy the URI connection string. Using the URI connection string, do the following:

  1. Extract the host string. For example, consider the following URI:

    mongodb://admin:<PASSWORD>@mongo1.example.net:27017,mongo2.example.net:27017,mongo3.example.net:27017/<DATABASE>?ssl=true&replicaSet=GettingStarted&authSource=admin
    

    The Host String consists of the comma separated list between the @ symbol and the / symbol:

    mongo1.example.net:27017,mongo2.example.net:27017,mongo3.example.net:27017
    
  2. Extract the replica set name. In the URI connection string, the replica set name is associated to the replicaSet query parameter:

    replicaSet=GettingStarted
    
  3. Assemble the cluster host string in replicaSetName/<host1>,<host2>,<host3> format. For example, given the information retrieved in the previous steps, the Free Tier cluster host string would look as follows:

    GettingStarted/mongo1.example.net:27017,mongo2.example.net:27017,mongo3.example.net:27017
    

The following operation imports data from primer-dataset.json into the restaurants collection in the guidebook database. Make the following changes:

  • Replace the <username> and <password> with the administrative username and password you chose during cluster creation.
  • Replace the <clusterHostString> with the cluster host string assembled in the previous step.
wget -qO- https://raw.githubusercontent.com/mongodb/docs-assets/primer-dataset/primer-dataset.json | \
  mongoimport --host <clusterHostString> \
  --ssl -u <username> -p '<password>' --authenticationDatabase admin  \
  --db "guidebook" --collection "restaurants"

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. For example:

    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 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.