dynobase-icon
Dynobase

DynamoDB CLI Commands & Query Examples Cheat Sheet

Written by Rafal Wilinski

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

Setup

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:

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.

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.

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.

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.

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:

Dynobase is a Professional GUI Client for DynamoDB

Start your 7-day free trial today

Product Features

© 2020 Dynobase

+
Still using AWS DynamoDB Console?
Try Dynobase to accelerate your DynamoDB workflow. Start your 7-day free trial today.