DynamoDB Scan: Examples, Parallel Scans and Read Costs

A DynamoDB Scan reads items across a table or secondary index, returning one service page at a time. Each request evaluates up to 1 MB of data or its Limit of items before applying a filter. Use Scan for work that needs to inspect the whole dataset, with pagination and a read budget; use a key-based access pattern for recurring application lookups.

When to use DynamoDB Scan

Scan fits an occasional audit, a bounded administrative inspection, or a migration that must examine each item. It can also be reasonable for a small table when the measured read cost and latency fit the workload. There is no universal table-size threshold below which scans are automatically safe: request frequency and available capacity matter too.

A scan can enumerate keys for a cleanup job, but deleting or changing those items is separate write work. If data changes during the traversal, define how the job handles new, updated or already-deleted items. For analytics or a reproducible export, consider exporting to S3, which does not consume table read capacity and requires point-in-time recovery.

A sparse secondary index can make a scan smaller because only qualifying items have index entries. That saving comes from the index's contents and projected item size, not from adding a filter to the scan. For the full access-pattern comparison, see DynamoDB Query vs Scan.

AWS CLI scan examples

The simplest command is valid, but AWS CLI v2 follows all pages automatically:

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

For a controlled first inspection, make one request and inspect its continuation key:

aws dynamodb scan \
  --table-name MyTable \
  --limit 100 \
  --no-paginate \
  --return-consumed-capacity TOTAL \
  --output json \
  --no-cli-pager
aws dynamodb scan \
  --table-name MyTable \
  --limit 100 \
  --no-paginate \
  --return-consumed-capacity TOTAL \
  --output json \
  --no-cli-pager

--limit 100 caps evaluated items for that service call; the byte limit can stop it earlier. --no-cli-pager affects terminal display only. To resume manually, save the returned LastEvaluatedKey map as last-key.json and add --exclusive-start-key file://last-key.json to the same command. Stop when no key remains.

For CLI-managed output batches, use --max-items and --starting-token instead. These use a CLI NextToken, not the raw DynamoDB key. The pagination guide shows both approaches and their different token formats.

ScanCommand with AWS SDK for JavaScript v3

Install @aws-sdk/client-dynamodb and @aws-sdk/lib-dynamodb, configure a Region and credentials, and run this as an ES module. The example uses MyTable, with String keys pk and sk and a status attribute.

import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
import { DynamoDBDocumentClient, ScanCommand } from "@aws-sdk/lib-dynamodb"

const client = DynamoDBDocumentClient.from(new DynamoDBClient({}))
let startKey
let consumed = 0
let evaluated = 0
let matched = 0

do {
  const page = await client.send(new ScanCommand({
    TableName: "MyTable",
    Limit: 100,
    FilterExpression: "#status = :status",
    ProjectionExpression: "#pk, #sk, #status",
    ExpressionAttributeNames: { "#pk": "pk", "#sk": "sk", "#status": "status" },
    ExpressionAttributeValues: { ":status": "ARCHIVED" },
    ReturnConsumedCapacity: "TOTAL",
    ...(startKey ? { ExclusiveStartKey: startKey } : {}),
  }))

  for (const item of page.Items ?? []) console.log(item)
  consumed += page.ConsumedCapacity?.CapacityUnits ?? 0
  evaluated += page.ScannedCount ?? 0
  matched += page.Count ?? 0
  startKey = page.LastEvaluatedKey
} while (startKey && Object.keys(startKey).length > 0)

console.log({ consumed, evaluated, matched })
import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
import { DynamoDBDocumentClient, ScanCommand } from "@aws-sdk/lib-dynamodb"

const client = DynamoDBDocumentClient.from(new DynamoDBClient({}))
let startKey
let consumed = 0
let evaluated = 0
let matched = 0

do {
  const page = await client.send(new ScanCommand({
    TableName: "MyTable",
    Limit: 100,
    FilterExpression: "#status = :status",
    ProjectionExpression: "#pk, #sk, #status",
    ExpressionAttributeNames: { "#pk": "pk", "#sk": "sk", "#status": "status" },
    ExpressionAttributeValues: { ":status": "ARCHIVED" },
    ReturnConsumedCapacity: "TOTAL",
    ...(startKey ? { ExclusiveStartKey: startKey } : {}),
  }))

  for (const item of page.Items ?? []) console.log(item)
  consumed += page.ConsumedCapacity?.CapacityUnits ?? 0
  evaluated += page.ScannedCount ?? 0
  matched += page.Count ?? 0
  startKey = page.LastEvaluatedKey
} while (startKey && Object.keys(startKey).length > 0)

console.log({ consumed, evaluated, matched })

Import ScanCommand from @aws-sdk/lib-dynamodb when using DynamoDBDocumentClient. This command accepts plain values. The command of the same name from @aws-sdk/client-dynamodb is the low-level version and expects typed DynamoDB JSON instead.

This loop processes all pages without accumulating the table in memory. For large jobs, add pacing between requests and checkpoint after processing each page. A checkpoint should include the table, index, scan parameters and continuation key so a restart does not accidentally resume a different job.

Scan in Python with boto3

The boto3 client exposes a Scan paginator. Its values use DynamoDB JSON type descriptors:

import boto3

client = boto3.client("dynamodb")
paginator = client.get_paginator("scan")

for page in paginator.paginate(
    TableName="MyTable",
    FilterExpression="#status = :status",
    ExpressionAttributeNames={"#status": "status"},
    ExpressionAttributeValues={":status": {"S": "ARCHIVED"}},
    ReturnConsumedCapacity="TOTAL",
    PaginationConfig={"PageSize": 100},
):
    for item in page.get("Items", []):
        print(item)
    print(page.get("ConsumedCapacity"))
import boto3

client = boto3.client("dynamodb")
paginator = client.get_paginator("scan")

for page in paginator.paginate(
    TableName="MyTable",
    FilterExpression="#status = :status",
    ExpressionAttributeNames={"#status": "status"},
    ExpressionAttributeValues={":status": {"S": "ARCHIVED"}},
    ReturnConsumedCapacity="TOTAL",
    PaginationConfig={"PageSize": 100},
):
    for item in page.get("Items", []):
        print(item)
    print(page.get("ConsumedCapacity"))

The paginator follows LastEvaluatedKey even when a filtered page has no items. If you use the resource interface's Table.scan() instead, supply native Python values and implement the continuation loop yourself.

DynamoDB Scan filtering and ProjectionExpression

FilterExpression decides which evaluated items remain in the response. ProjectionExpression decides which attributes of those items are returned. Neither reduces the capacity consumed for the same table items.

aws dynamodb scan \
  --table-name MyTable \
  --filter-expression '#status = :status' \
  --projection-expression '#pk, #sk, #status' \
  --expression-attribute-names '{"#pk":"pk","#sk":"sk","#status":"status"}' \
  --expression-attribute-values '{":status":{"S":"ARCHIVED"}}' \
  --limit 100 \
  --no-paginate \
  --return-consumed-capacity TOTAL
aws dynamodb scan \
  --table-name MyTable \
  --filter-expression '#status = :status' \
  --projection-expression '#pk, #sk, #status' \
  --expression-attribute-names '{"#pk":"pk","#sk":"sk","#status":"status"}' \
  --expression-attribute-values '{":status":{"S":"ARCHIVED"}}' \
  --limit 100 \
  --no-paginate \
  --return-consumed-capacity TOTAL

Scan can filter on key attributes as well as ordinary attributes. It does not accept KeyConditionExpression. For comparison operators, functions and nested fields, use the FilterExpression reference.

ScannedCount measures the candidates evaluated by a request; Count measures the matches after filtering. Neither is a whole-table total unless that request covered the whole table. Select: "COUNT" avoids returning items but still consumes read capacity. Sum page counts when an exact traversal count is needed, and account for concurrent data changes.

When scanning a GSI, set IndexName and request only attributes projected into that index. A GSI cannot fetch missing attributes from the base table. Choosing an index with smaller projected records can reduce read work, whereas projecting fewer attributes from the same scan does not. AWS describes these behaviors in the Scan guide.

Read consistency and ordering

Scan uses eventually consistent reads by default. ConsistentRead: true, or CLI --consistent-read, requests strong reads of individual table or local-secondary-index items. Global secondary indexes support eventual consistency only.

Strong reads do not make the scan a point-in-time snapshot. An item read later can reflect a write that occurred after earlier items were read. Use a point-in-time export when that distinction matters for analysis or reconciliation. The Scan API reference explicitly states that strong Scan reads do not provide snapshot isolation.

Do not use Scan as an ordered application feed. It traverses storage, with partition-key values in arbitrary order. Query is the operation for reading an item collection in sort-key order.

How much does a DynamoDB scan cost?

Read cost depends on evaluated data, consistency and capacity mode. A filter that returns one item after scanning a large dataset still incurs the read work for that dataset. The AWS read-capacity documentation explains the accounting and minimum charges.

For an illustrative full 1 MB page consisting of 4 KB items:

Strong reads:     1,024 KB / 4 KB = 256 read units
Eventual reads:   256 / 2 = 128 read units
Strong reads:     1,024 KB / 4 KB = 256 read units
Eventual reads:   256 / 2 = 128 read units

On-demand Standard-table reads in US East (N. Virginia) cost $0.125 per million read request units. At that rate, the eventual-read example costs 128 / 1,000,000 × $0.125 = $0.000016 in read charges for that page. Repeating scans frequently multiplies those charges. This is an illustration, not an exact formula from table storage size: actual item sizes, page boundaries, empty partitions and retries can affect measured consumption. See DynamoDB pricing for Region and table-class rates.

Provisioned tables pay for allocated capacity over time; a scan consumes that shared capacity and can throttle other reads. It does not acquire a separate per-scan dollar charge. Use ReturnConsumedCapacity on requests to measure the job, and estimate recurring workloads with the pricing calculator.

How fast is a scan?

A complete scan's work grows with the dataset it evaluates. Elapsed time also depends on available throughput, item sizes, request latency, throttling and worker concurrency, so there is no fixed scan-speed promise. A restrictive filter reduces response bytes but does not eliminate that underlying read work.

Smaller pages let a worker pause between calls and reduce bursts. They do not make reading the whole table free. Track consumed capacity, throttled requests, job progress and the application's own read latency while tuning a scan. AWS scan best practices recommend controlling bursts and isolating scan workloads where possible.

Parallel Scan in DynamoDB

Parallel Scan divides the scan into logical segments that independent workers can traverse. Each request includes Segment and TotalSegments. Segment numbers are zero-based; every worker must agree on TotalSegments and resume a segment with that segment's own continuation key.

With the same client as the JavaScript example, this starts four workers as an illustrative configuration:

const totalSegments = 4

async function scanSegment(segment) {
  let startKey
  do {
    const page = await client.send(new ScanCommand({
      TableName: "MyTable",
      Segment: segment,
      TotalSegments: totalSegments,
      Limit: 100,
      ReturnConsumedCapacity: "TOTAL",
      ...(startKey ? { ExclusiveStartKey: startKey } : {}),
    }))
    for (const item of page.Items ?? []) console.log(segment, item)
    startKey = page.LastEvaluatedKey
  } while (startKey && Object.keys(startKey).length > 0)
}

await Promise.all(Array.from({ length: totalSegments }, (_, segment) => scanSegment(segment)))
const totalSegments = 4

async function scanSegment(segment) {
  let startKey
  do {
    const page = await client.send(new ScanCommand({
      TableName: "MyTable",
      Segment: segment,
      TotalSegments: totalSegments,
      Limit: 100,
      ReturnConsumedCapacity: "TOTAL",
      ...(startKey ? { ExclusiveStartKey: startKey } : {}),
    }))
    for (const item of page.Items ?? []) console.log(segment, item)
    startKey = page.LastEvaluatedKey
  } while (startKey && Object.keys(startKey).length > 0)
}

await Promise.all(Array.from({ length: totalSegments }, (_, segment) => scanSegment(segment)))

Four is not a recommended universal worker count. Increase concurrency only while the table and application have capacity to spare. Logical segments are not physical DynamoDB partitions, and they need not finish together. A distributed job should record completed segments as well as in-progress cursors, and avoid two workers processing the same segment unintentionally.

Parallelism can finish a job sooner by consuming available capacity faster. It does not reduce the data that must be read and can increase throttling if the workers compete with live traffic. DynamoDB Local does not faithfully support segmented parallel scans, so verify segment behavior against the managed service.

Restricting Scan through IAM

An identity policy can explicitly deny the Scan API:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Deny",
    "Action": "dynamodb:Scan",
    "Resource": "*"
  }]
}
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Deny",
    "Action": "dynamodb:Scan",
    "Resource": "*"
  }]
}

The denial applies to identities governed by that policy; merely creating the policy does not restrict an entire organization. Scope it to the intended roles or enforce an appropriate organization policy. Also review PartiQL permissions separately: denying the Scan action alone does not express a blanket ban on PartiQL SELECT statements that perform full scans. The PartiQL IAM documentation describes its permission model.

Running a scan deliberately

Before starting, define what completeness means, select the source table or index, and choose a throughput budget. Process and checkpoint pages without retaining the whole table in memory. Slow or stop workers if throttling or application latency rises. Dynobase scan controls provide scan cost estimates, streaming scans and pause/resume for interactive work.