DynamoDB CLI Operation Examples
This cheat sheet will help you perform basic query operations, table manipulations and item updates with DynamoDB and AWS CLI.
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
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
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.
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:
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
If you're having problems with this part, head to our guide on handling AWS Credentials & profiles.
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.
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.
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:
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
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.
To get a list of all DynamoDB Tables available on your account in the current region, use following command:
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.
To request a full, on-demand backup of DynamoDB table, use the following command:
Backups are created asynchronously and without consuming any of the provisioned throughput.
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.
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.
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
Restoring the table from backup will not set it's tags, autoscaling policies, stream settings, TTL settings, and CloudWatch Metrics.
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
ExpressionAttributeValues. The following command will only return items where
lastName attribute equals
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:
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
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.
Deleting an item can be only made using its primary key:
Deletes can also be made conditionally:
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
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.
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
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
LastEvaluatedKey in the place of
starting-token will allow you to get all the data matching Key conditions.
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
Instead of using
expression-attribute-values, you might use
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.
© 2021 Dynobase