DynamoDB Scan in Python (boto3)

scan reads every item in a table or index, page by page, then optionally drops rows with a filter. With the boto3 low-level client you write the FilterExpression with #/: placeholders and typed values (DynamoDB JSON), and the built-in scan paginator walks every page for you.

Code

import boto3

client = boto3.client("dynamodb")

paginator = client.get_paginator("scan")

items = []
for page in paginator.paginate(
    TableName="Music",
    FilterExpression="#filter0 >= :filterValue0",
    ExpressionAttributeNames={"#filter0": "Year"},
    ExpressionAttributeValues={":filterValue0": {"N": "2010"}},
):
    items.extend(page["Items"])

print(f"Matched {len(items)} items")

Explanation

• FilterExpression — applied after the read, on the server; it shrinks the response, not the cost. You pay to read every item scanned. The filtered attribute is aliased (#filter0 → Year), which keeps reserved words like Year safe.
• ExpressionAttributeValues — the :placeholder → typed-value map in DynamoDB JSON ({"N": "2010"}).
• Pagination is mandatory — each page reads at most 1 MB before filtering, so a filtered page can be empty while more data remains. client.get_paginator("scan") follows LastEvaluatedKey for you; each page carries an Items list.
• For a large full-table scan, parallelize with Segment / TotalSegments.
• Items return in DynamoDB JSON. Prefer native Python types (and the Attr filter helper)? Use the resource API (Table.scan), which returns numbers as decimal.Decimal.
• Prefer query. scan reads the whole table; on anything but a tiny table it's slow and expensive.

Do it visually

The DynamoDB Expression Builder assembles the FilterExpression + name/value maps and copies runnable code.

To explore tables in a GUI — filtered, paginated result grids and copy-as-code — download DynoTable, instead of scanning blind from a script.

Related guides

• Query vs. Scan — when (rarely) a scan is justified.
• Why is my DynamoDB Scan slow and expensive? — the cost model and how to avoid it.
• DynamoDB ProvisionedThroughputExceededException — what a full-table scan does to a provisioned table's capacity.
• DynamoDB ThrottlingException — the other throttle, and how exponential backoff handles it.

References

• Scan — Amazon DynamoDB API Reference
• scan — Boto3 DynamoDB.Client Reference
• Scan paginator — Boto3 DynamoDB Reference
• Scanning tables — Amazon DynamoDB Developer Guide

Last verified 2026-07-13 against the official AWS documentation linked above.