DynamoDB CLI Commands & Query Examples Cheat Sheet

DynamoDB CLI Operation Examples

This cheat sheet will help you perform basic query operations, table manipulations and item updates with DynamoDB and AWS CLI.

If you're looking for similar cheat sheet but for Python, you can find it here, and for Node.js - here.

Table of Contents

• Setting up
• Important Environment Variables
• Create Table
• Human-friendly way of creating tables
• Outputting Cloudformation templates
• Delete Table
• List Tables
• Describe Table
• Create Backup
• List Backups
• Describe Backup
• Restore Table from Backup
• Get All Items / Scan
• Get Item
• Put Item
• Query Set of Items
• Update Item
• Increment Item Attribute
• Delete Item
• Query with Sorting
• Query Pagination
• Running operations against Local DynamoDB

Setup

Before we start, make sure you have aws CLI installed by running following command in your terminal:

aws --version
aws --version

If this command fails, please install the AWS CLI first. The easiest way to do that on macOS is to use brew:

brew install awscli
brew install awscli

Moreover, to verify your credentials are setup correctly, run this command:

aws sts get-caller-identity
aws sts get-caller-identity

It should return your current IAM identity that you're using for communication with AWS.

Important Environment Variables

What if you have multiple AWS profiles set up, and your tables are provisioned in multiple, non-default regions? You can use special environment variables to prefix the commands with them and tell the CLI to use different profiles, regions, and adjust its behavior. Here's the list of them:

• AWS_DEFAULT_REGION - e.g. `us-east-1, changes the region used for operation
• AWS_PROFILE - changes the profile used for the operation
• AWS_DEFAULT_OUTPUT - changes the format of the response. One of the following: json, yaml, text, table
• AWS_CA_BUNDLE - specifies the path to a certificate bundle to use for HTTPS certificate validation.
• AWS_SHARED_CREDENTIALS_FILE - specify the path to the location of the file where profiles information is contained, by default it's ~/.aws/credentials

For example:

$ AWS_PROFILE=dev AWS_DEFAULT_OUTPUT=table AWS_DEFAULT_REGION=us-east-1 aws sts get-caller-identity

---------------------------------------------------------
|                   GetCallerIdentity                   |
+---------+---------------------------------------------+
|  Account|  0123456789012                              |
|  Arn    |  arn:aws:iam::0123456789012:user/admin      |
|  UserId |  AIXAJX3DRXTIXV3KZXXXX                      |
+---------+---------------------------------------------+
$ AWS_PROFILE=dev AWS_DEFAULT_OUTPUT=table AWS_DEFAULT_REGION=us-east-1 aws sts get-caller-identity

---------------------------------------------------------
|                   GetCallerIdentity                   |
+---------+---------------------------------------------+
|  Account|  0123456789012                              |
|  Arn    |  arn:aws:iam::0123456789012:user/admin      |
|  UserId |  AIXAJX3DRXTIXV3KZXXXX                      |
+---------+---------------------------------------------+

If you're having problems with this part, head to our guide on handling AWS Credentials & profiles.

Create Table

Table is the very basic data container in DynamoDB, so if you want to save some data in DynamoDB, first you need to create a table. You can do that in AWS CLI like this:

aws dynamodb create-table \
    --table-name MyTableName \
    --attribute-definitions AttributeName=id,AttributeType=S AttributeName=createdAt,AttributeType=S \
    --key-schema AttributeName=id,KeyType=HASH AttributeName=createdAt,KeyType=RANGE \
    --provisioned-throughput ReadCapacityUnits=1,WriteCapacityUnits=1
aws dynamodb create-table \
    --table-name MyTableName \
    --attribute-definitions AttributeName=id,AttributeType=S AttributeName=createdAt,AttributeType=S \
    --key-schema AttributeName=id,KeyType=HASH AttributeName=createdAt,KeyType=RANGE \
    --provisioned-throughput ReadCapacityUnits=1,WriteCapacityUnits=1

This call will create a DynamoDB table called MyTable with composite primary key where attribute id is the Hash Key, and createdAt is the Range Key. It means that items with the same id will be assigned to the same partition, and they will be sorted on the date of their creation.

Moreover, we're specifying --provisioned-throughput argument which will create a table in provisioned capacity mode with just one Write Capacity Unit (WCU) and one Read Capacity Unit (RCU).

If you don't like the "shorthand syntax" where input parameters are specified in comma-separated fashion, you can also use JSON format like this:

aws dynamodb create-table \
    --table-name MyTableName \
    --attribute-definitions '[{"AttributeName":"id", "AttributeType":"S"}, {"AttributeName":"createdAt", "AttributeType":"S"}]' \
    --key-schema '[{"AttributeName":"id", "KeyType":"HASH"}, {"AttributeName":"createdAt", "KeyType":"RANGE"}]' \
    --provisioned-throughput '{"ReadCapacityUnits": 1, "WriteCapacityUnits": 1}'
aws dynamodb create-table \
    --table-name MyTableName \
    --attribute-definitions '[{"AttributeName":"id", "AttributeType":"S"}, {"AttributeName":"createdAt", "AttributeType":"S"}]' \
    --key-schema '[{"AttributeName":"id", "KeyType":"HASH"}, {"AttributeName":"createdAt", "KeyType":"RANGE"}]' \
    --provisioned-throughput '{"ReadCapacityUnits": 1, "WriteCapacityUnits": 1}'

The same format can be used for all following commands.

Human-friendly way of creating tables

Recently, AWS added a new command which makes creating DynamoDB tables much simpler:

aws dynamodb wizard new-table
aws dynamodb wizard new-table

It does not require you to memorize all these parameters and guides you through table creation step-by-step, like so:

> aws dynamodb wizard new-table
Enter the name of the table: my-new-table
Enter the name of the primary key: pk
Primary key type: String
Add a sort key? Yes
Enter the name of the sort key: sk
Sort key type: String
Select the read/write capacity mode.
Enter read capacity units: 10
Enter write capacity units: 5
> aws dynamodb wizard new-table
Enter the name of the table: my-new-table
Enter the name of the primary key: pk
Primary key type: String
Add a sort key? Yes
Enter the name of the sort key: sk
Sort key type: String
Select the read/write capacity mode.
Enter read capacity units: 10
Enter write capacity units: 5

Outputting Cloudformation Table Templates

If CLI is not fitting into your provisioning model beause you're using Cloudformation, CDK or Serverless Framework, the good new is that you can still leverage CLI to generate templates that can be reused in your software by adding --generate-cli-skeleton flag at the end:

aws dynamodb create-table --table-name MyTableName \
    --attribute-definitions '[{"AttributeName":"id", "AttributeType":"S"}, {"AttributeName":"createdAt", "AttributeType":"S"}]' \
    --key-schema '[{"AttributeName":"id", "KeyType":"HASH"}, {"AttributeName":"createdAt", "KeyType":"RANGE"}]' \
    --provisioned-throughput '{"ReadCapacityUnits": 1, "WriteCapacityUnits": 1}' \
     --generate-cli-skeleton > my-table-template.json
aws dynamodb create-table --table-name MyTableName \
    --attribute-definitions '[{"AttributeName":"id", "AttributeType":"S"}, {"AttributeName":"createdAt", "AttributeType":"S"}]' \
    --key-schema '[{"AttributeName":"id", "KeyType":"HASH"}, {"AttributeName":"createdAt", "KeyType":"RANGE"}]' \
    --provisioned-throughput '{"ReadCapacityUnits": 1, "WriteCapacityUnits": 1}' \
     --generate-cli-skeleton > my-table-template.json

Table definition will be saved to the my-table-template.json file.

If you don't like putting complicated commands on your own, take a look at our DynamoDB table schema designer or Download Dynobase and create tables using Dynobase.

Delete Table

To delete the DynamoDB table using AWS CLI, use the following command:

aws dynamodb delete-table \
    --table-name NameOfTheTableThatShouldBeDeleted
aws dynamodb delete-table \
    --table-name NameOfTheTableThatShouldBeDeleted

This operation will not only remove the table, but also the data inside and related DynamoDB Streams, so double check before executing it.

Also, in order to delete a table, it must be in an ACTIVE state. After this command is executed, the table will not be removed instantly. Instead, it will transition into a DELETING state and will be ultimately be deleted after few minutes.

List Tables

To get a list of all DynamoDB Tables available on your account in the current region, use following command:

aws dynamodb list-tables
aws dynamodb list-tables

Describe Table

To get information about the table, use Describe Table operation. It will return data about table key schema, capacity mode, provisioned WCU and RCU, count of the items, status, amount of bytes, and much more.

aws dynamodb describe-table \
    --table-name NameOfTheTableThatShouldBeDeleted
aws dynamodb describe-table \
    --table-name NameOfTheTableThatShouldBeDeleted

Backup Table

To request a full, on-demand backup of DynamoDB table, use the following command:

aws dynamodb create-backup \
    --table-name NameOfTheTableThatShouldBeBackedUp
    --backup-name MyBackup
aws dynamodb create-backup \
    --table-name NameOfTheTableThatShouldBeBackedUp
    --backup-name MyBackup

It will not only backup all the data but table key structure, LSIs and GSIs, Streams, and information about provisioned read and write capacity.

Backups are created asynchronously and without consuming any of the provisioned throughput.

Listing Backups

After you've created your backup, you might want to make sure it was created and see other ones created in the past. That's where list-backups command comes to play. By default, command aws dynamodb list-backups will return you backups for all of your tables.

If you want to list only backups for specific table between two dates (in epoch format), use following command:

aws dynamodb list-backups \
    --table-name my-table \
    --time-range-lower-bound 1577836800 \
    --time-range-upper-bound 1583020800 \
    --backup-type USER
aws dynamodb list-backups \
    --table-name my-table \
    --time-range-lower-bound 1577836800 \
    --time-range-upper-bound 1583020800 \
    --backup-type USER

Command will return an Array called BackupSummaries containing info about backups' status, size, creation date, related table and so on.

Describe Backup

If you want to confirm that you're about to restore a table from the correct backup, you can use aws dynamodb describe-backup to do so.

aws dynamodb describe-backup \
    --backup-arn arn:aws:dynamodb:us-east-1:123456789012:table/my-table/backup/123456789012-bbbcccddd
aws dynamodb describe-backup \
    --backup-arn arn:aws:dynamodb:us-east-1:123456789012:table/my-table/backup/123456789012-bbbcccddd

Since this table is rate-limited to only 10 calls per second, use it wisely.

Restore Table from Backup

Once you have a backup of your table, you might want to restore it. Running following command will create a new DynamoDB Table containing data from backup specified in backup-arn.

aws dynamodb restore-table-from-backup \
    --target-table-name NameOfTheTableThatShouldBeCreatedFromBackup
    --backup-arn ARNOfTheBackup
aws dynamodb restore-table-from-backup \
    --target-table-name NameOfTheTableThatShouldBeCreatedFromBackup
    --backup-arn ARNOfTheBackup

Restoring the table from backup will not set it's tags, autoscaling policies, stream settings, TTL settings, and CloudWatch Metrics.

Get All Items / Scan

To run a Scan operation, which is used to fetch a collection of items, use this command:

aws dynamodb scan \
    --table-name NameOfTheTableToBeScanned
aws dynamodb scan \
    --table-name NameOfTheTableToBeScanned

Single Scan operation can return up to a maximum of 1 MB of data. Results can be narrowed down using a combination of FilterExpressions and ExpressionAttributeValues. The following command will only return items where lastName attribute equals Doe.

aws dynamodb scan \
    --table-name NameOfTheTableToBeScanned
    --filter-expression "lastName = :name" \
    --expression-attribute-values '{":name":{"S":"Doe"}}'
aws dynamodb scan \
    --table-name NameOfTheTableToBeScanned
    --filter-expression "lastName = :name" \
    --expression-attribute-values '{":name":{"S":"Doe"}}'

If you want to prevent from creating huge and unreadable CLI commands, you can reference json files too:

aws dynamodb scan \
    --table-name NameOfTheTableToBeScanned \
    --filter-expression "lastName = :lastName" \
    --projection-expression "#AA, #BB" \
    --expression-attribute-names file://expression-attribute-names.json \
    --expression-attribute-values file://expression-attribute-values.json
aws dynamodb scan \
    --table-name NameOfTheTableToBeScanned \
    --filter-expression "lastName = :lastName" \
    --projection-expression "#AA, #BB" \
    --expression-attribute-names file://expression-attribute-names.json \
    --expression-attribute-values file://expression-attribute-values.json

where the contents of expression-attribute-names.json file look like this:

{
    "#BB": "createdAt",
    "#AA":"deletedAt"
}
{
    "#BB": "createdAt",
    "#AA":"deletedAt"
}

and the contents of expression-attribute-values.json file look like this:

{
    ":lastName": "Doe"
}
{
    ":lastName": "Doe"
}

Get Item

If you know the table's Key Schema and want to get a particular item by its key or combination of keys (when using composite key), you can use GetItem operation:

aws dynamodb get-item \
    --table-name NameOfTheTable \
    --key '{"id": {"S": "123"}, "email": {"S": "john@doe.com"}}'
    --consistent-read # This is optional
aws dynamodb get-item \
    --table-name NameOfTheTable \
    --key '{"id": {"S": "123"}, "email": {"S": "john@doe.com"}}'
    --consistent-read # This is optional

Put Item

Inserting a new record to DynamoDB can be done using put-item operation. You can reference the item that is to be inserted inline:

aws dynamodb put-item \
    --table-name NameOfTheTable \
    --item '{"id":"123"}'
aws dynamodb put-item \
    --table-name NameOfTheTable \
    --item '{"id":"123"}'

or by referencing external JSON file:

aws dynamodb put-item \
    --table-name NameOfTheTable \
    --item file://item.json \
aws dynamodb put-item \
    --table-name NameOfTheTable \
    --item file://item.json \

Keep in mind that if there's an existing item with the same primary key as the new item in the specified table, the new item completely replaces the existing item.

Delete Item

Deleting an item can be only made using its primary key:

aws dynamodb delete-item \
    --table-name NameOfTheTable \
    --key '{"id": {"S": "123"}, "email": {"S": "john@doe.com"}}'
aws dynamodb delete-item \
    --table-name NameOfTheTable \
    --key '{"id": {"S": "123"}, "email": {"S": "john@doe.com"}}'

Deletes can also be made conditionally:

aws dynamodb delete-item \
    --table-name NameOfTheTable \
    --key '{"id": {"S": "123"}, "email": {"S": "john@doe.com"}}'
    --condition-expression 'attribute_not_exists(updatedAt)'
aws dynamodb delete-item \
    --table-name NameOfTheTable \
    --key '{"id": {"S": "123"}, "email": {"S": "john@doe.com"}}'
    --condition-expression 'attribute_not_exists(updatedAt)'

Query Set of Items

The Query operation finds items based on primary key values. You can query any table or secondary index that has a composite primary key:

aws dynamodb query \
    --table-name NameOfTheTable \
    --key-condition-expression "id = :myId" \
    --expression-attribute-values '{":v1": {"S": "Fire Walk With Me"}}'
aws dynamodb query \
    --table-name NameOfTheTable \
    --key-condition-expression "id = :myId" \
    --expression-attribute-values '{":v1": {"S": "Fire Walk With Me"}}'

If you want to narrow down the query results on a non-index attribute, you can combine it with FilterExpression:

aws dynamodb query \
    --table-name NameOfTheTable \
    --key-condition-expression "id = :myId" \
    --expression-attribute-values '{":v1": {"S": "Fire Walk With Me"}}'
    --filter-expression 'attribute_not_exists(updatedAt)'
aws dynamodb query \
    --table-name NameOfTheTable \
    --key-condition-expression "id = :myId" \
    --expression-attribute-values '{":v1": {"S": "Fire Walk With Me"}}'
    --filter-expression 'attribute_not_exists(updatedAt)'

Keep in mind that FilterExpression is applied after the items have already been read; the process of filtering does not reduce consumed read capacity units.

Query With Sorting

Sorting in DynamoDB can only be made on an attribute that is indexed as a sort key. To control the order of the query results, use scan-index-forward param:

aws dynamodb query \
    --table-name NameOfTheTable \
    --key-condition-expression "id = :myId" \
    --expression-attribute-values '{":v1": {"S": "Fire Walk With Me"}}'
    --filter-expression 'attribute_not_exists(updatedAt)'
    --scan-index-forward
aws dynamodb query \
    --table-name NameOfTheTable \
    --key-condition-expression "id = :myId" \
    --expression-attribute-values '{":v1": {"S": "Fire Walk With Me"}}'
    --filter-expression 'attribute_not_exists(updatedAt)'
    --scan-index-forward

Query Pagination

Because DynamoDB Query results are limited to the 1MB of data, it's possible that the first Query operation will not return all the results you're aiming to fetch. To get all of the items matching query criteria, you must use "Pagination". In DynamoDB, pagination is consisting of two pieces:

• NextToken - return value which tells when the Query operation last stopped
• starting-token - parameter which tells where the next Query operation should start

Putting LastEvaluatedKey in the place of starting-token will allow you to get all the data matching Key conditions.

aws dynamodb query \
    --table-name NameOfTheTable \
    --key-condition-expression "id = :myId" \
    --expression-attribute-values '{":v1": {"S": "Fire Walk With Me"}}'
    --filter-expression 'attribute_not_exists(updatedAt)'
    --scan-index-forward
    --starting-token '<VALUE_OF_NEXT_TOKEN_FROM_PREV_OPERATION>'
aws dynamodb query \
    --table-name NameOfTheTable \
    --key-condition-expression "id = :myId" \
    --expression-attribute-values '{":v1": {"S": "Fire Walk With Me"}}'
    --filter-expression 'attribute_not_exists(updatedAt)'
    --scan-index-forward
    --starting-token '<VALUE_OF_NEXT_TOKEN_FROM_PREV_OPERATION>'

Learn more about Pagination in DynamoDB.

Update Item

To update an item, you must know its key and update-expression which tells CLI which attributes should be updated and what should happen with them:

aws dynamodb update-item \
    --table-name NameOfTheTable \
    --key '{"id":{"S":"John-123"}}' \
    --update-expression "SET HomeAddress = :h, DOB = :d" \
    --expression-attribute-values '{":h": { "S": "Menlo Park 1" },":d": { "S": "1234568990" }}' \
    --return-values ALL_NEW
aws dynamodb update-item \
    --table-name NameOfTheTable \
    --key '{"id":{"S":"John-123"}}' \
    --update-expression "SET HomeAddress = :h, DOB = :d" \
    --expression-attribute-values '{":h": { "S": "Menlo Park 1" },":d": { "S": "1234568990" }}' \
    --return-values ALL_NEW

If your update-expression contains one of the reserved keywords, you'll have to use the expression-attribute-names

Increment Item Attribute

Instead of using update-expression and expression-attribute-values, you might use attribute-updates shorthand:

aws dynamodb update-item \
    --table-name NameOfTheTable \
    --key '{"id":{"S":"John-123"}}' \
    --attribute-updates '{"version": {"Value": {"N": "1"},"Action": "ADD"}}' \
    --return-values ALL_NEW
aws dynamodb update-item \
    --table-name NameOfTheTable \
    --key '{"id":{"S":"John-123"}}' \
    --attribute-updates '{"version": {"Value": {"N": "1"},"Action": "ADD"}}' \
    --return-values ALL_NEW

Running operations against Local DynamoDB

DynamoDB can be also ran locally for test purposes. If you want to run your commands against local tables, you can end your commands with --endpoint-url=http://localhost:<port>. For instance:

aws dynamodb list-tables --endpoint-url http://localhost:8000 --region us-east-1
aws dynamodb list-tables --endpoint-url http://localhost:8000 --region us-east-1

For more instructions, head to our article on Running DynamoDB Locally.