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
- Delete Table
- Describe Table
- Create 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
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
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.
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 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.
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
© 2020 Dynobase