# aws dynamodb scan

AWS CLI commands · Updated 16 November 2026

**Short answer:** aws dynamodb scan --table-name my-table reads every item in a table or index and returns them, page by page. Add --filter-expression to drop items you do not want and --projection-expression to return fewer attributes, but remember a scan always reads, and bills for, the whole table.

## What the command does

A scan walks the table from start to finish in 1 MB pages. The CLI follows `LastEvaluatedKey` automatically, so a single command can make thousands of requests on a big table and print every item. That is fine for a small configuration table or a one-off export, and a bad idea for a large production table under load, because it competes with your application for read capacity.

If you know the partition key of what you are after, use [query](https://cloudconsole.dev/cli/dynamodb-query) instead. Scan is for when you genuinely need everything, or when no index fits the question.

## Syntax

```
aws dynamodb scan --table-name <table> \
  [--index-name <index>] \
  [--filter-expression "..."] [--projection-expression "..."] \
  [--expression-attribute-names '{...}'] \
  [--expression-attribute-values '{...}'] \
  [--select COUNT] [--max-items <n>] \
  [--total-segments <n> --segment <i>]
```

## Worked examples

**Peek at a few items** to see what the data looks like:

```
aws dynamodb scan --table-name feature-flags --max-items 5
```

**Filter** for items matching a condition. Reserved words such as `status` need a name placeholder:

```
aws dynamodb scan --table-name jobs \
  --filter-expression "#s = :failed AND attempts >= :n" \
  --expression-attribute-names '{"#s":"status"}' \
  --expression-attribute-values '{":failed":{"S":"FAILED"},":n":{"N":"3"}}'
```

**Export just two attributes as text**, one item per line:

```
aws dynamodb scan --table-name users \
  --projection-expression "userId, email" \
  --query "Items[].[userId.S, email.S]" --output text > users.tsv
```

**Count items exactly** (it still reads the whole table):

```
aws dynamodb scan --table-name users --select COUNT --query Count
```

The CLI adds up `Count` across pages for you. For a rough figure without the read cost, [describe-table](https://cloudconsole.dev/cli/dynamodb-describe-table) shows `ItemCount`, refreshed periodically.

**Parallel scan** a large table from four terminals or processes, one segment each:

```
aws dynamodb scan --table-name events --total-segments 4 --segment 0 > seg0.json
aws dynamodb scan --table-name events --total-segments 4 --segment 1 > seg1.json
# ... segments 2 and 3 in parallel
```

## Key options

| Option | What it controls |
|---|---|
| `--filter-expression` | Server-side filter applied after items are read. Reduces output, not cost. |
| `--projection-expression` | Attributes to return. Smaller output, same read cost. |
| `--limit` | Items evaluated per request (before filtering). Useful to slow a scan down. |
| `--max-items` / `--starting-token` | CLI paging: stop after N items and resume later with the printed `NextToken`. |
| `--total-segments` / `--segment` | Split the table into segments that separate workers scan independently. |
| `--consistent-read` | Strongly consistent reads, at twice the read cost; not available on global secondary indexes. |

## Gotchas

- **Cost scales with table size.** On an on-demand table, every full scan is billed for every item read. On a provisioned table, a scan can consume the read capacity your application needs and cause [ProvisionedThroughputExceededException](https://cloudconsole.dev/errors/dynamodb-provisionedthroughputexceeded).
- **Filters with `--limit` return odd pages.** A page can contain zero matches but still have more data behind it. Keep going until there is no `LastEvaluatedKey`, or let the CLI paginate.
- **The output is typed JSON.** Use `--query` to unwrap values (`email.S`, `total.N`) before piping into other tools.
- **Large exports belong elsewhere.** For full-table exports, DynamoDB's export to S3 (which needs point-in-time recovery enabled) does not consume table read capacity.
- **Results are not ordered** across partitions. Do not rely on scan order.

## Questions

### How do I limit the number of results from aws dynamodb scan?

Use --max-items N to stop after N items; the CLI prints a NextToken you can pass to --starting-token to continue. --limit controls how many items each request evaluates, which is not the same thing when you filter.

### How do I scan with a filter in the AWS CLI?

Pass --filter-expression with placeholders, for example "attempts >= :n", and supply the values with --expression-attribute-values '{":n":{"N":"3"}}'. Use --expression-attribute-names for reserved words.

### Is scan or query faster in DynamoDB?

Query, almost always, because it reads only one partition key's items. Scan reads the whole table regardless of filters.

## When this happens away from your desk

A runaway scan shows up as read throttling on the table. CloudConsole is built to show DynamoDB throttling alarms and the table they belong to on your phone.

[About the CloudConsole app](https://cloudconsole.dev/aws-console-app) · [Download on the App Store](https://apps.apple.com/app/cloudconsole-for-aws/id6835419710)

## Sources

- [aws dynamodb scan (AWS CLI Command Reference)](https://docs.aws.amazon.com/cli/latest/reference/dynamodb/scan.html)
- [Scanning tables in DynamoDB (Developer Guide)](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Scan.html)

## Related

- [aws dynamodb query](https://cloudconsole.dev/cli/dynamodb-query)
- [aws dynamodb describe-table](https://cloudconsole.dev/cli/dynamodb-describe-table)
- [aws dynamodb batch-write-item](https://cloudconsole.dev/cli/dynamodb-batch-write-item)
- [ProvisionedThroughputExceededException](https://cloudconsole.dev/errors/dynamodb-provisionedthroughputexceeded)
- [CloudWatch alarm for DynamoDB ReadThrottleEvents (table)](https://cloudconsole.dev/alarms/dynamodb-readthrottleevents)
- [aws dynamodb create-table](https://cloudconsole.dev/cli/dynamodb-create-table)

---

Source: https://cloudconsole.dev/cli/dynamodb-scan

CloudConsole is an independent iPhone and Android app for Amazon Web Services by Cloudconcur Ltd. It is not affiliated with Amazon Web Services.
