DynamoDB CLI Commands & Query Examples Cheat Sheet

Rafal Wilinski

Written by Rafal Wilinski

Published on June 18th, 2020

Still using AWS console to work with DynamoDB? 🙈

Time to 10x your DynamoDB productivity with Dynobase [learn more]

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


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

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

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

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:

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:

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:

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:

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

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:

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:

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:

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.

Backup Table

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

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:

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.

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.

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:

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.

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

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

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

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:

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:

or by referencing external JSON file:

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:

Deletes can also be made conditionally:

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:

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

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:

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.

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:

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:

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:

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

Tired of AWS Console? Try Dynobase.

First 7 days are on us. No strings attached.

Product Features

Member Portal
© 2024 Dynobase