Introduction

Reading data from DynamoDB with the AWS CLI is straightforward once you choose the right command for the access pattern. Use get-item for one exact primary key, query for multiple items that share a partition key, and scan only when you truly need to inspect the whole table.

Get One Item by Primary Key

get-item is the most direct way to fetch a single record. You must provide the full primary key in DynamoDB's typed JSON format.

1aws dynamodb get-item \
2  --table-name Orders \
3  --key '{
4    "orderId": {"S": "ORD-1001"}
5  }'

If the table uses a composite primary key, include both key attributes:

1aws dynamodb get-item \
2  --table-name Orders \
3  --key '{
4    "customerId": {"S": "CUST-9"},
5    "orderId": {"S": "ORD-1001"}
6  }'

The response contains an Item field when a match exists. If the item is missing, the command still succeeds, but Item is absent.

Query Multiple Items Efficiently

When you need several items from the same partition, use query. This is fast because it uses the table key design rather than reading everything.

1aws dynamodb query \
2  --table-name Orders \
3  --key-condition-expression "customerId = :customer" \
4  --expression-attribute-values '{
5    ":customer": {"S": "CUST-9"}
6  }'

You can add sort-key conditions as well:

1aws dynamodb query \
2  --table-name Orders \
3  --key-condition-expression "customerId = :customer AND orderId BETWEEN :from AND :to" \
4  --expression-attribute-values '{
5    ":customer": {"S": "CUST-9"},
6    ":from": {"S": "ORD-1000"},
7    ":to": {"S": "ORD-1999"}
8  }'

If you only need a few attributes, add a projection expression to reduce payload size:

1aws dynamodb query \
2  --table-name Orders \
3  --key-condition-expression "customerId = :customer" \
4  --projection-expression "orderId, orderStatus, total" \
5  --expression-attribute-values '{
6    ":customer": {"S": "CUST-9"}
7  }'

Projection expressions reduce response size, but they do not change which items DynamoDB reads to satisfy the key condition. They are still useful for CLI workflows because the output becomes easier to inspect, pipe to jq, or hand off to another command.

Use scan Only as a Last Resort

scan reads the table broadly and is usually the most expensive option. It is useful for ad hoc inspection, migration work, or tables without a queryable access pattern for the data you need.

1aws dynamodb scan \
2  --table-name Orders \
3  --filter-expression "orderStatus = :status" \
4  --expression-attribute-values '{
5    ":status": {"S": "SHIPPED"}
6  }'

A filter expression on scan does not make the read efficient. DynamoDB still examines the scanned items first and filters afterward.

Control Consistency and Output

By default, DynamoDB reads are eventually consistent. If your workflow needs the most recent committed value and the table supports it, enable strong consistency on get-item or query:

1aws dynamodb get-item \
2  --table-name Orders \
3  --key '{
4    "orderId": {"S": "ORD-1001"}
5  }' \
6  --consistent-read

For shell pipelines, combine the CLI output with --output json and a jq filter so you can inspect only the fields you care about instead of scrolling through the full response.

Common Pitfalls

• Using scan when get-item or query would work. That increases latency and read cost.
• Forgetting DynamoDB attribute types such as "S", "N", and "BOOL" in the CLI JSON input.
• Expecting get-item to fail when the item is absent. It returns no Item instead.
• Omitting part of a composite primary key. get-item needs the full key.
• Confusing filter expressions with key conditions. Filters narrow returned data, but they do not change how much data DynamoDB reads.

Summary

• Use get-item for one exact key lookup.
• Use query for multiple items that share a partition key, optionally with sort-key conditions.
• Use scan sparingly because it is the least efficient read pattern.
• Provide keys and expression values in DynamoDB's typed JSON format.
• Add projection expressions when you want smaller, cheaper responses.