DynamoDB CLI Commands and Query Examples

Use aws dynamodb query with --key-condition-expression to read items by a partition key and optional sort key condition. AWS CLI v2 expects DynamoDB JSON values such as {"S":"customer-123"}, follows paginated reads automatically, and uses --query only to reshape output locally. The examples below use one consistent table schema and include filters, indexes, sorting, counts and reusable JSON request files.

Command index

• Setup and environment variables
• Create a table, interactive setup, CLI JSON and CloudFormation
• Delete, list and describe tables
• Create, list, describe and restore backups
• Scan, get, put and query items
• Sort results, paginate, update, increment and delete items
• Use DynamoDB Local

Setup

Check that the installed CLI reports version 2, and confirm which identity will run the commands:

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

If necessary, use the AWS CLI installation instructions. For an IAM Identity Center profile, run aws sso login --profile dev before using it. The examples use POSIX shell quoting, suitable for bash or zsh; other shells can require different escaping.

The table is MyTableName, with String partition key id and String sort key createdAt. Items for a customer share id; timestamps use a consistent UTC format so lexicographic sorting matches time order. This example assumes each timestamp uniquely identifies an item within its customer. The GSI example uses an additional status-createdAt-index with String partition key status and String sort key createdAt.

Important environment variables

AWS_PROFILE=dev AWS_REGION=us-east-1 AWS_DEFAULT_OUTPUT=json aws sts get-caller-identity
AWS_PROFILE=dev AWS_REGION=us-east-1 AWS_DEFAULT_OUTPUT=json aws sts get-caller-identity

You can also append --profile dev --region us-east-1 to a command. Keep these settings consistent across table creation and later reads; a table in another Region will look missing. --no-cli-pager disables display paging without disabling API pagination. The CLI environment variable reference documents precedence.

Create a table

Create an on-demand table and wait until it can accept reads and writes:

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 \
  --billing-mode PAY_PER_REQUEST

aws dynamodb wait table-exists --table-name MyTableName
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 \
  --billing-mode PAY_PER_REQUEST

aws dynamodb wait table-exists --table-name MyTableName

HASH means partition key and RANGE means sort key. Define key attributes only in --attribute-definitions; ordinary fields do not need declarations. For provisioned capacity, replace the billing-mode line with --billing-mode PROVISIONED --provisioned-throughput ReadCapacityUnits=1,WriteCapacityUnits=1, choosing values appropriate to the workload.

JSON syntax is also accepted. This is an alternative to the preceding creation command, not a second step:

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"}]' \
  --billing-mode PAY_PER_REQUEST
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"}]' \
  --billing-mode PAY_PER_REQUEST

Interactive table creation

CLI v2 auto-prompt helps complete a command without memorizing every parameter:

aws dynamodb create-table --cli-auto-prompt
aws dynamodb create-table --cli-auto-prompt

Use a different table name if you already created the example table. The table schema designer is another way to prepare a CreateTable payload.

CLI skeletons are not CloudFormation templates

--generate-cli-skeleton input emits a CLI input document, not an infrastructure template. Edit its fields and remove options you do not need before submitting it:

aws dynamodb create-table --generate-cli-skeleton input > create-table-input.json
aws dynamodb create-table --cli-input-json file://create-table-input.json
aws dynamodb create-table --generate-cli-skeleton input > create-table-input.json
aws dynamodb create-table --cli-input-json file://create-table-input.json

Skeleton contents can change between CLI versions. For CloudFormation, use an actual resource definition instead:

Resources:
  ExampleTable:
    Type: AWS::DynamoDB::Table
    Properties:
      TableName: MyTableName
      BillingMode: PAY_PER_REQUEST
      AttributeDefinitions:
        - AttributeName: id
          AttributeType: S
        - AttributeName: createdAt
          AttributeType: S
      KeySchema:
        - AttributeName: id
          KeyType: HASH
        - AttributeName: createdAt
          KeyType: RANGE
Resources:
  ExampleTable:
    Type: AWS::DynamoDB::Table
    Properties:
      TableName: MyTableName
      BillingMode: PAY_PER_REQUEST
      AttributeDefinitions:
        - AttributeName: id
          AttributeType: S
        - AttributeName: createdAt
          AttributeType: S
      KeySchema:
        - AttributeName: id
          KeyType: HASH
        - AttributeName: createdAt
          KeyType: RANGE

Do not deploy this definition over the manually created example table without an appropriate import plan. Dynobase infrastructure code generation can generate CloudFormation, CDK or Terraform for a table.

Delete a table

This deletes the table and its items. Run it only when finished with the example data:

aws dynamodb delete-table --table-name MyTableName
aws dynamodb wait table-not-exists --table-name MyTableName
aws dynamodb delete-table --table-name MyTableName
aws dynamodb wait table-not-exists --table-name MyTableName

Deletion is asynchronous and deletion protection, when enabled, blocks it. Deleting a table also disables its stream; already retained stream records remain subject to their retention period. The DeleteTable API describes allowed states and deletion behavior.

List tables

aws dynamodb list-tables --output json --no-cli-pager
aws dynamodb list-tables --query 'TableNames' --output text --no-cli-pager
aws dynamodb list-tables --output json --no-cli-pager
aws dynamodb list-tables --query 'TableNames' --output text --no-cli-pager

This lists tables for the current account and Region. The CLI automatically follows service pages. Here --query is a JMESPath output selector, not a DynamoDB Query expression. See the list-tables reference.

Describe a table

aws dynamodb describe-table \
  --table-name MyTableName \
  --query 'Table.{Status:TableStatus,Keys:KeySchema,Indexes:GlobalSecondaryIndexes}' \
  --output json
aws dynamodb describe-table \
  --table-name MyTableName \
  --query 'Table.{Status:TableStatus,Keys:KeySchema,Indexes:GlobalSecondaryIndexes}' \
  --output json

Remove --query to inspect the full response, including capacity settings and storage statistics. ItemCount is maintained asynchronously and is not an exact current count for an application query.

Create an on-demand backup

aws dynamodb create-backup \
  --table-name MyTableName \
  --backup-name MyTableName-manual \
  --query 'BackupDetails.BackupArn' \
  --output text
aws dynamodb create-backup \
  --table-name MyTableName \
  --backup-name MyTableName-manual \
  --query 'BackupDetails.BackupArn' \
  --output text

Save the returned ARN in a shell variable named BACKUP_ARN for the following examples. Backup creation is asynchronous and does not consume table read capacity. A backup is not a promise that all operational settings will be restored automatically.

List backups

aws dynamodb list-backups \
  --table-name MyTableName \
  --time-range-lower-bound '2026-10-01T00:00:00Z' \
  --time-range-upper-bound '2026-11-01T00:00:00Z' \
  --backup-type USER
aws dynamodb list-backups \
  --table-name MyTableName \
  --time-range-lower-bound '2026-10-01T00:00:00Z' \
  --time-range-upper-bound '2026-11-01T00:00:00Z' \
  --backup-type USER

Omit the time bounds for all dates, or omit --table-name to list backups across tables in the selected Region. Results appear in BackupSummaries.

Describe a backup

aws dynamodb describe-backup --backup-arn "$BACKUP_ARN"
aws dynamodb describe-backup --backup-arn "$BACKUP_ARN"

Confirm the source table and that the backup is available before restoring it. Use the ARN from actual output rather than constructing one from a table name.

Restore a table from backup

aws dynamodb restore-table-from-backup \
  --target-table-name MyTableName-restored \
  --backup-arn "$BACKUP_ARN"

aws dynamodb wait table-exists --table-name MyTableName-restored
aws dynamodb restore-table-from-backup \
  --target-table-name MyTableName-restored \
  --backup-arn "$BACKUP_ARN"

aws dynamodb wait table-exists --table-name MyTableName-restored

Restore creates a new table. Reconfigure settings such as auto scaling, IAM policies, alarms, tags, Streams, TTL and point-in-time recovery as needed. The restore documentation lists the settings that require attention.

Get all items with Scan

aws dynamodb scan --table-name MyTableName --output json --no-cli-pager
aws dynamodb scan --table-name MyTableName --output json --no-cli-pager

The command follows all pages. For a single bounded service request, add --limit 100 --no-paginate. To return only customers named Doe from each evaluated page:

aws dynamodb scan \
  --table-name MyTableName \
  --filter-expression '#lastName = :lastName' \
  --expression-attribute-names '{"#lastName":"lastName"}' \
  --expression-attribute-values '{":lastName":{"S":"Doe"}}' \
  --limit 100 \
  --no-paginate
aws dynamodb scan \
  --table-name MyTableName \
  --filter-expression '#lastName = :lastName' \
  --expression-attribute-names '{"#lastName":"lastName"}' \
  --expression-attribute-values '{":lastName":{"S":"Doe"}}' \
  --limit 100 \
  --no-paginate

This is still a scan. Choose the access operation using Query vs Scan, and use FilterExpression syntax for more predicates.

Use JSON files for expressions

Save this as expression-attribute-names.json:

{"#id":"id","#created":"createdAt","#lastName":"lastName"}
{"#id":"id","#created":"createdAt","#lastName":"lastName"}

Save this as expression-attribute-values.json:

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

Then run:

aws dynamodb scan \
  --table-name MyTableName \
  --filter-expression '#lastName = :lastName' \
  --projection-expression '#id, #created' \
  --expression-attribute-names file://expression-attribute-names.json \
  --expression-attribute-values file://expression-attribute-values.json \
  --limit 100 \
  --no-paginate
aws dynamodb scan \
  --table-name MyTableName \
  --filter-expression '#lastName = :lastName' \
  --projection-expression '#id, #created' \
  --expression-attribute-names file://expression-attribute-names.json \
  --expression-attribute-values file://expression-attribute-values.json \
  --limit 100 \
  --no-paginate

CLI expression values require the S, N, BOOL and other type wrappers even when read from a file. Numbers use strings inside N; Booleans use JSON Booleans inside BOOL.

Get one item

Supply both key attributes for this table:

aws dynamodb get-item \
  --table-name MyTableName \
  --key '{"id":{"S":"customer-123"},"createdAt":{"S":"2026-10-01T10:00:00Z"}}' \
  --consistent-read
aws dynamodb get-item \
  --table-name MyTableName \
  --key '{"id":{"S":"customer-123"},"createdAt":{"S":"2026-10-01T10:00:00Z"}}' \
  --consistent-read

--consistent-read is optional. An absent item produces no Item field. If the key schema differs from the example, update every key consistently rather than changing only one command.

Put an item

aws dynamodb put-item \
  --table-name MyTableName \
  --item '{"id":{"S":"customer-123"},"createdAt":{"S":"2026-10-01T10:00:00Z"},"status":{"S":"OPEN"},"lastName":{"S":"Doe"},"version":{"N":"1"}}' \
  --condition-expression 'attribute_not_exists(id)'
aws dynamodb put-item \
  --table-name MyTableName \
  --item '{"id":{"S":"customer-123"},"createdAt":{"S":"2026-10-01T10:00:00Z"},"status":{"S":"OPEN"},"lastName":{"S":"Doe"},"version":{"N":"1"}}' \
  --condition-expression 'attribute_not_exists(id)'

The condition makes this an insert-only example. Without it, put-item replaces the whole existing item with that primary key. You can place the same typed item JSON in item.json and use --item file://item.json instead.

Query a set of items

Partition key equality

aws dynamodb query \
  --table-name MyTableName \
  --key-condition-expression '#id = :id' \
  --expression-attribute-names '{"#id":"id"}' \
  --expression-attribute-values '{":id":{"S":"customer-123"}}'
aws dynamodb query \
  --table-name MyTableName \
  --key-condition-expression '#id = :id' \
  --expression-attribute-names '{"#id":"id"}' \
  --expression-attribute-values '{":id":{"S":"customer-123"}}'

The partition key requires equality. Query works on a partition-key-only table too; a sort key is needed only for sort-key conditions and ordering within an item collection.

Sort key range

aws dynamodb query \
  --table-name MyTableName \
  --key-condition-expression '#id = :id AND #created BETWEEN :start AND :end' \
  --expression-attribute-names '{"#id":"id","#created":"createdAt"}' \
  --expression-attribute-values '{":id":{"S":"customer-123"},":start":{"S":"2026-10-01T00:00:00Z"},":end":{"S":"2026-10-31T23:59:59Z"}}'
aws dynamodb query \
  --table-name MyTableName \
  --key-condition-expression '#id = :id AND #created BETWEEN :start AND :end' \
  --expression-attribute-names '{"#id":"id","#created":"createdAt"}' \
  --expression-attribute-values '{":id":{"S":"customer-123"},":start":{"S":"2026-10-01T00:00:00Z"},":end":{"S":"2026-10-31T23:59:59Z"}}'

BETWEEN includes both endpoints. This example assumes timestamps stored at whole-second precision. If you store fractional seconds, choose bounds that match that representation. For a month prefix, use begins_with(#created, :prefix) with :prefix set to {"S":"2026-10"} instead of the range condition and range placeholders.

Filter and project non-key attributes

aws dynamodb query \
  --table-name MyTableName \
  --key-condition-expression '#id = :id' \
  --filter-expression '#status = :status' \
  --projection-expression '#id, #created, #status' \
  --expression-attribute-names '{"#id":"id","#created":"createdAt","#status":"status"}' \
  --expression-attribute-values '{":id":{"S":"customer-123"},":status":{"S":"OPEN"}}' \
  --return-consumed-capacity TOTAL
aws dynamodb query \
  --table-name MyTableName \
  --key-condition-expression '#id = :id' \
  --filter-expression '#status = :status' \
  --projection-expression '#id, #created, #status' \
  --expression-attribute-names '{"#id":"id","#created":"createdAt","#status":"status"}' \
  --expression-attribute-values '{":id":{"S":"customer-123"},":status":{"S":"OPEN"}}' \
  --return-consumed-capacity TOTAL

Filters run after reads and do not reduce consumed capacity. Projection reduces response attributes, not the read charge. To select items without updatedAt, replace the filter with attribute_not_exists(#updated), add the corresponding alias, and remove the now-unused :status value.

Query a secondary index

This requires status-createdAt-index to exist with status as its partition key and createdAt as its sort key:

aws dynamodb query \
  --table-name MyTableName \
  --index-name status-createdAt-index \
  --key-condition-expression '#status = :status' \
  --expression-attribute-names '{"#status":"status"}' \
  --expression-attribute-values '{":status":{"S":"OPEN"}}'
aws dynamodb query \
  --table-name MyTableName \
  --index-name status-createdAt-index \
  --key-condition-expression '#status = :status' \
  --expression-attribute-names '{"#status":"status"}' \
  --expression-attribute-values '{":status":{"S":"OPEN"}}'

Use the index's key schema, not the base table's. GSIs support eventual consistency only and can return only projected attributes. A low-cardinality status-only key is an illustration, not a universal production index design.

Count matching items

aws dynamodb query \
  --table-name MyTableName \
  --key-condition-expression '#id = :id' \
  --expression-attribute-names '{"#id":"id"}' \
  --expression-attribute-values '{":id":{"S":"customer-123"}}' \
  --select COUNT \
  --output json
aws dynamodb query \
  --table-name MyTableName \
  --key-condition-expression '#id = :id' \
  --expression-attribute-names '{"#id":"id"}' \
  --expression-attribute-values '{":id":{"S":"customer-123"}}' \
  --select COUNT \
  --output json

COUNT reads the same candidates and consumes read capacity. With automatic pagination the CLI aggregates page counts. Do not combine COUNT with a projection expression. With --no-paginate, the count covers just one service page.

Save a complete query input

Save this as query-input.json:

{
  "TableName": "MyTableName",
  "KeyConditionExpression": "#id = :id",
  "ExpressionAttributeNames": {"#id":"id"},
  "ExpressionAttributeValues": {":id":{"S":"customer-123"}},
  "ReturnConsumedCapacity": "TOTAL"
}
{
  "TableName": "MyTableName",
  "KeyConditionExpression": "#id = :id",
  "ExpressionAttributeNames": {"#id":"id"},
  "ExpressionAttributeValues": {":id":{"S":"customer-123"}},
  "ReturnConsumedCapacity": "TOTAL"
}

aws dynamodb query --cli-input-json file://query-input.json
aws dynamodb query --cli-input-json file://query-input.json

The CLI Query reference documents all request fields. Keep request JSON separate from output-selection expressions supplied through --query.

Query with sorting

Reverse sort-key order with --no-scan-index-forward:

aws dynamodb query \
  --table-name MyTableName \
  --key-condition-expression '#id = :id' \
  --expression-attribute-names '{"#id":"id"}' \
  --expression-attribute-values '{":id":{"S":"customer-123"}}' \
  --no-scan-index-forward
aws dynamodb query \
  --table-name MyTableName \
  --key-condition-expression '#id = :id' \
  --expression-attribute-names '{"#id":"id"}' \
  --expression-attribute-values '{":id":{"S":"customer-123"}}' \
  --no-scan-index-forward

Ascending is the default. DynamoDB sorts by the selected table or index's sort key; this flag does not sort arbitrary attributes. To read only the most recent item without a filter, add --limit 1 --no-paginate.

Query pagination

aws dynamodb query \
  --cli-input-json file://query-input.json \
  --page-size 25 \
  --max-items 25 \
  --output json
aws dynamodb query \
  --cli-input-json file://query-input.json \
  --page-size 25 \
  --max-items 25 \
  --output json

If the output contains NextToken, set TOKEN to that exact string and resume:

aws dynamodb query \
  --cli-input-json file://query-input.json \
  --page-size 25 \
  --max-items 25 \
  --starting-token "$TOKEN" \
  --output json
aws dynamodb query \
  --cli-input-json file://query-input.json \
  --page-size 25 \
  --max-items 25 \
  --starting-token "$TOKEN" \
  --output json

For manual pagination, use --no-paginate and pass the service's LastEvaluatedKey map to --exclusive-start-key. Never put LastEvaluatedKey in --starting-token. --page-size controls each underlying call, whereas --max-items controls CLI output. The pagination guide covers empty filtered pages and SDK equivalents.

Update an item

aws dynamodb update-item \
  --table-name MyTableName \
  --key '{"id":{"S":"customer-123"},"createdAt":{"S":"2026-10-01T10:00:00Z"}}' \
  --update-expression 'SET #status = :status' \
  --condition-expression 'attribute_exists(id)' \
  --expression-attribute-names '{"#status":"status"}' \
  --expression-attribute-values '{":status":{"S":"CLOSED"}}' \
  --return-values ALL_NEW
aws dynamodb update-item \
  --table-name MyTableName \
  --key '{"id":{"S":"customer-123"},"createdAt":{"S":"2026-10-01T10:00:00Z"}}' \
  --update-expression 'SET #status = :status' \
  --condition-expression 'attribute_exists(id)' \
  --expression-attribute-names '{"#status":"status"}' \
  --expression-attribute-values '{":status":{"S":"CLOSED"}}' \
  --return-values ALL_NEW

Aliases handle reserved words. The existence condition prevents this example from creating a new item if its key is absent. Without a condition, UpdateItem can create an item. See the update-item reference.

Increment an attribute

aws dynamodb update-item \
  --table-name MyTableName \
  --key '{"id":{"S":"customer-123"},"createdAt":{"S":"2026-10-01T10:00:00Z"}}' \
  --update-expression 'ADD #version :one' \
  --condition-expression 'attribute_exists(id)' \
  --expression-attribute-names '{"#version":"version"}' \
  --expression-attribute-values '{":one":{"N":"1"}}' \
  --return-values UPDATED_NEW
aws dynamodb update-item \
  --table-name MyTableName \
  --key '{"id":{"S":"customer-123"},"createdAt":{"S":"2026-10-01T10:00:00Z"}}' \
  --update-expression 'ADD #version :one' \
  --condition-expression 'attribute_exists(id)' \
  --expression-attribute-names '{"#version":"version"}' \
  --expression-attribute-values '{":one":{"N":"1"}}' \
  --return-values UPDATED_NEW

This atomically adds one to a Number attribute, using zero as the starting value if the attribute is missing. Repeating the successful command increments again, so it is not an idempotent retry mechanism.

Delete an item

Delete only if the item's status is still CLOSED:

aws dynamodb delete-item \
  --table-name MyTableName \
  --key '{"id":{"S":"customer-123"},"createdAt":{"S":"2026-10-01T10:00:00Z"}}' \
  --condition-expression '#status = :status' \
  --expression-attribute-names '{"#status":"status"}' \
  --expression-attribute-values '{":status":{"S":"CLOSED"}}' \
  --return-values ALL_OLD
aws dynamodb delete-item \
  --table-name MyTableName \
  --key '{"id":{"S":"customer-123"},"createdAt":{"S":"2026-10-01T10:00:00Z"}}' \
  --condition-expression '#status = :status' \
  --expression-attribute-names '{"#status":"status"}' \
  --expression-attribute-values '{":status":{"S":"CLOSED"}}' \
  --return-values ALL_OLD

Remove the condition and its expression maps for an unconditional delete. ALL_OLD returns the removed item, when present. A conditional failure means the write was not applied.

Run commands against DynamoDB Local

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

Use the same endpoint option on every command intended for the local database. The DynamoDB Local setup guide covers local credentials and starting the service. Local behavior does not prove managed-service capacity or throttling behavior.