Setting Up Step 1: Create an elastic cluster Step 2: Create an Amazon Cloud9 environment Step 3: Install the mongo shell Step 4: Connect to your new elastic cluster Step 5: Shard your collection; insert and query data

Get started with Amazon DocumentDB elastic clusters

This getting started section walks you through on how you can create and query your first elastic cluster. There are many ways to connect and get started with elastic clusters. This guide uses Amazon Cloud9, a web-based terminal to connect and query your elastic cluster using the mongo shell directly from the Amazon Web Services Management Console.

Topics

Setting Up
Step 1: Create an elastic cluster
Step 2: Create an Amazon Cloud9 environment
Step 3: Install the mongo shell
Step 4: Connect to your new elastic cluster
Step 5: Shard your collection; insert and query data

Setting Up

If you would rather connect to your Amazon DocumentDB from your local machine by creating an SSH connection to an Amazon EC2 instance, please see Connecting with Amazon EC2.

Prerequisites

Before you create your first Amazon DocumentDB cluster, you must do the following:

Create an Amazon Web Services (Amazon) account

Before you can begin using Amazon DocumentDB, you must have an Amazon Web Services (Amazon) account. The Amazon account is free. You pay only for the services and resources that you use.

If you do not have an Amazon Web Services account, use the following procedure to create one.

To sign up for Amazon Web Services

Open http://www.amazonaws.cn/ and choose Sign Up.
Follow the on-screen instructions.

Set up the needed Amazon Identity and Access Management (IAM) permissions.

Access to manage Amazon DocumentDB resources such as clusters, instances, and cluster parameter groups requires credentials that Amazon can use to authenticate your requests. For more information, see Identity and Access Management for Amazon DocumentDB.

In the search bar of the Amazon Web Services Management Console, type in IAM and select IAM in the drop down menu.
Once you're in the IAM console, select Users from the navigation pane.
Select your username.
Click the button Add permissions.
Select Attach existing policies directly.
Type AmazonDocDBFullAccess in the search bar and select it once it appears in the search results.
Click the blue button at the bottom that says Next: Review.
Click the blue button at the bottom that says Add permissions.

Create an Amazon Virtual Private Cloud (Amazon VPC)

This step is only necessary if you don't already have a default Amazon VPC. If you don't, then complete step 1 of the Getting Started with Amazon VPC in the Amazon VPC User Guide. This will take less than five minutes.

Step 1: Create an elastic cluster

In this section we explain how to create a brand new elastic cluster, using either the Amazon Web Services Management Console or Amazon CLI with the following instructions.

Using the Amazon Web Services Management Console

To create an elastic cluster configuration using the Amazon Web Services Management Console:

Sign into the Amazon Web Services Management Console and open the Amazon DocumentDB console.
On the Amazon DocumentDB Management Console, under Clusters, choose Create.
On the Create Amazon DocumentDB cluster page, in the Cluster type section, choose Elastic Cluster.
On the Create Amazon DocumentDB cluster page, in the Configuration section, enter a unique cluster identifier (following the naming requirements below the field).
For the shard configuration fields:
1. In the Shard count field, enter the number of shards you want in your cluster. The maximum number of shards per cluster is 32.
  
  Note
  Two nodes will be deployed for each shard. Both nodes will have the same shard capacity.
2. In the Shard instance count field, choose the number of replica instances you want associated with each shard. The maximum number of shard instances is 16, in increments of 1. All replica instances have the same shard capacity as defined in the following field.
  
  Note
  The number of replica instances applies to all shards in the elastic cluster. A shard instance count value of 1 means there is one writer instance, and any additional instances are replicas that can be used for reads and to improve availability.
3. In the Shard capacity field, choose the number of virtual CPUs (vCPUs) you want associated with each shard instance. The maximum number of vCPUs per shard instance is 64. Allowed values are 2, 4, 8, 16, 32, 64.
In the Virtual Private Cloud (VPC) field, choose a VPC from the drop-down list.

For Subnets and VPC security groups, you can use the defaults or select three subnets of your choice and up to three VPC security groups (minimum one).
In the Authentication section, enter a string that identifies the the login name of the master user in the Username field.

In the Password field, enter a unique password that complies with the instructions.
In the Encryption section, keep the default settings.

Optionally, you can enter a Amazon KMS key ARN you created. For more information, see Data encryption at rest for Amazon DocumentDB elastic clusters.

Important
Encryption must be enabled for elastic clusters.
In the Backup section, edit the fields according to your backup requirements.
1. Backup retention period—In the list, choose the number of days to keep automatic backups of this cluster before deleting them.
2. Backup window—Set the daily time and duration during which Amazon DocumentDB is to make backups of this cluster.
  1. Choose Select window if you want to configure the time and duration when backups are created.
    
    Start time—In the first list, choose the start time hour (UTC) for starting your automatic backups. In the second list, choose the minute of the hour that you want automatic backups to begin.
    
    Duration—In the list, choose the number of hours to be allocated to creating automatic backups.
  2. Choose No preference if you want Amazon DocumentDB to choose the time and duration when backups are created.
In the Maintenance section, choose the day, time, and duration when modifications or patches are applied to your cluster.
Choose Create cluster.

The elastic cluster is now provisioning. This can take up to a few minutes to finish. You can connect to your cluster when the elastic cluster status shows as active in the Clusters list.

Using the Amazon CLI

To create an elastic cluster using the Amazon CLI, use the create-cluster operation with the following parameters:

--cluster-name—Required. The current name of the elastic scale cluster as entered during creation or last modified.
--shard-capacity—Required. The number of vCPUs assigned to each shard. Maximum is 64. Allowed values are 2, 4, 8, 16, 32, 64.
--shard-count—Required. The number of shards assigned to the cluster. Maximum is 32.
--shard-instance-count—Optional. The number of replica instances applying to all shards in this cluster. Maximum is 16.
--admin-user-name—Required. The username associated with the admin user.
--admin-user-password—Required. The password associated with the admin user.
--auth-type—Required. The authentication type used to determine where to fetch the password used for accessing the elastic cluster. Valid types are PLAIN_TEXT or SECRET_ARN.
--vpc-security-group-ids—Optional. Configure a list of EC2 VPC security groups to associate with this cluster.
--preferred-maintenance-window—Optional. Configure the weekly time range during which system maintenance can occur, in Universal Coordinated Time (UTC).

The format is: ddd:hh24:mi-ddd:hh24:mi. Valid days (ddd): Mon, Tue, Wed, Thu, Fri, Sat, Sun

The default is a 30-minute window selected at random from an 8-hour block of time for each Amazon Web Services Region, occurring on a random day of the week.

Minimum 30-minute window.
--kms-key-id—Optional. Configure the KMS key identifier for an encrypted cluster.

The KMS key identifier is the Amazon Resource Name (ARN) for the Amazon KMS encryption key. If you are creating a cluster using the same Amazon Web Services account that owns the KMS encryption key that is used to encrypt the new cluster, you can use the KMS key alias instead of the ARN for the KMS encryption key.

If an encryption key is not specified in KmsKeyId and if the StorageEncrypted parameter is true, Amazon DocumentDB uses your default encryption key.
--preferred-backup-window—Optional. The daily preferred time range during which automated backups are created. The default is a 30-minute window selected at random from an 8-hour block of time for each Amazon Web Services Region.
--backup-retention-period—Optional. The number of days for which automated backups are retained. The default value is 1.
--storage-encrypted—Optional. Configues whether the cluster is encrypted or not encrypted.

--no-storage-encrypted specifies that the cluster is not encrypted.
--subnet-ids—Optional. Configure network subnet Ids.

In the following example, replace each user input placeholder with your own information.

Note

The following examples include creation of a specific KMS key. To use the default KMS key, do not include the --kms-key-id parameter.

For Linux, macOS, or Unix:


aws docdb-elastic create-cluster \
     --cluster-name sample-cluster-123 \
     --shard-capacity 8 \
     --shard-count 4 \
     --shard-instance-count 3 \
     --auth-type PLAIN_TEXT \
     --admin-user-name testadmin \
     --admin-user-password testPassword \
     --vpc-security-group-ids ec-65f40350 \
     --kms-key-id arn:aws-cn:docdb-elastic:us-east-1:477568257630:cluster/b9f1d489-6c3e-4764-bb42-da62ceb7bda2 \
     --subnet-ids subnet-9253c6a3, subnet-9f1b5af9 \
     --preferred-backup-window 18:00-18:30 \ 
     --backup-retention-period 7

For Windows:


aws docdb-elastic create-cluster ^
     --cluster-name sample-cluster-123 ^
     --shard-capacity 8 ^
     --shard-count 4 ^
     --shard-instance-count 3 ^
     --auth-type PLAIN_TEXT ^
     --admin-user-name testadmin ^
     --admin-user-password testPassword ^
     --vpc-security-group-ids ec-65f40350 ^
     --kms-key-id arn:aws-cn:docdb-elastic:us-east-1:477568257630:cluster/b9f1d489-6c3e-4764-bb42-da62ceb7bda2 ^
     --subnet-ids subnet-9253c6a3, subnet-9f1b5af9 \
     --preferred-backup-window 18:00-18:30 \ 
     --backup-retention-period 7

Step 2: Create an Amazon Cloud9 environment

Amazon Cloud9 provides a web-based terminal that you can use to connect to and query your Amazon DocumentDB elastic clusters using the mongo shell.

Note

Note: Your Amazon Cloud9 environment must be in the same security group as your instance. You can change the security group in the Amazon EC2 console.

Use your Amazon account and access the Amazon Web Services Management Console.
Navigate to the Amazon Cloud9 Console. You can type "Cloud9" in the Search field to locate it.
On the Amazon Cloud9 environment home page, choose Create environment.
On the Name environment page, in the Name field, enter a name of your choosing.

Choose Next step.
In Environment settings under the Environment type section, select, Create a new EC2 instance for environment (direct access).

Under the Instance type section, select an appropriate instance type for your network.

Under the Platform section, select Amazon Linux 2 (recommended).
Expand Network settings (advanced).

Choose the VPC and one of the subnets that you used when creating your elastic cluster.

Choose Next step.
Review your Amazon Cloud9 configuration.

If your configuration is correct, choose Create environment.

Step 3: Install the mongo shell

Once yours Amazon Cloud9 environment is ready, you are ready to connect to your cluster. Next, install the mongo shell in your Amazon Cloud9 environment that you created in Step 3. The mongo shell is a command-line utility that you use to connect and query your elastic cluster.

If your Amazon Cloud9 environment is still open from Step 3, go back to that environment and skip to instruction 3. If you navigated away from you Amazon Cloud9 environment, in the Amazon Cloud9 console, under Your environments, find the environment labeled with the name you set in the previous step. Choose Open IDE.

At the command prompt, create the repository file with the following command:


echo -e "[mongodb-org-4.0] \nname=MongoDB Repository\nbaseurl=https://repo.mongodb.org/yum/amazon/2013.03/mongodb-org/4.0/x86_64/\ngpgcheck=1 \nenabled=1 \ngpgkey=https://www.mongodb.org/static/pgp/server-4.0.asc" | sudo tee /etc/yum.repos.d/mongodb-org-4.0.repo

When it is complete, install the mongo shell with the following command:

sudo yum install -y mongodb-org-shell

Step 4: Connect to your new elastic cluster

Connect to your cluster using the mongo shell that you installed in Step 4.

On the Amazon DocumentDB Management Console, under Clusters, locate your cluster. Sort by role to display all clusters with the role Elastic Cluster.
Choose the cluster you created by selecting the cluster identifier. From Connectivity and Security, copy your endpoint and paste it into your Amazon Cloud9 environment.
Once connected, you should see the following output:

Step 5: Shard your collection; insert and query data

Elastic clusters add support for sharding in Amazon DocumentDB. Now that you are connected to your cluster, you can shard the cluster, insert data and run a few queries.

To shard a collection, enter the following:

sh.shardCollection("db.Employee1" , { "Employeeid" : "hashed" })
To insert a single document, enter the following:

db.Employee1.insert({"Employeeid":1, "Name":"Joe", "LastName": "Bruin", "level": 1 })

The following output is displayed:

WriteResult({ "nInserted" : 1 })
To read the document that you wrote, enter the findOne() command (it returns a single document):

db.Employee1.findOne()

The following output is displayed:
```
{
"_id" : ObjectId("61f344e0594fe1a1685a8151"),
"EmployeeID" : 1,
"Name" : "Joe",
"LastName" : "Bruin",
"level" : 1
}
```

To perform a few more queries, consider a gaming profile use case. First, insert a few entries into a collection titled "Employee". Enter the following:


db.Employee1.insertMany([
    { "Employeeid" : 1, "name" : "Matt", "lastname": "Winkle", "level": 12},
    { "Employeeid" : 2, "name" : "Frank", "lastname": "Chen", "level": 2},
    { "Employeeid" : 3, "name" : "Karen", "lastname": "William", "level": 7},
    { "Employeeid" : 4, "name" : "Katie", "lastname": "Schaper", "level": 3}
])

The following output is displayed:

{ "acknowledged" : true, "insertedIds" : [ 1, 2, 3, 4 ] }

To return all the documents in the profiles collection, enter the find() command:

db.Employee1.find()

The data you entered in step 4 is displayed.
To query a single document, include a filter (for example: "Katie"). Enter the following:

db.Employee1.find({name: "Katie"})

The following output is displayed:

{ "_id" : 4, "name" : "Katie", "lastname": "Schaper", "level": 3}

To find a profile and modify it, enter the findAndModify command. In this example, the employee "Matt" is given a higher level of "14":


db.Employee1.findAndModify({     
    query: { "Employeeid" : 1, "name" : "Matt"},     
    update: { "Employeeid" : 1, "name" : "Matt", "lastname" : "Winkle", "level" : 14 } 
})

The following output is displayed (note that the level has not changed yet):


{
    "_id" : 1,
    "name" : "Matt",
    "lastname" : "Winkle",
    "level" : 12,
}

To verify the level increase, enter the following query:

db.Employee1.find({name: "Matt"})

The following output is displayed:

{ "_id" : 1, "name" : "Matt", "lastname" : "winkle", "level" : 14 }

Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

How it works

Best Practices

Get started with Amazon DocumentDB elastic clusters

Topics

Setting Up

Prerequisites

To sign up for Amazon Web Services

Step 1: Create an elastic cluster

Note

Note

Important

Note

Step 2: Create an Amazon Cloud9 environment

Note

Step 3: Install the mongo shell

Step 4: Connect to your new elastic cluster

Step 5: Shard your collection; insert and query data