Busca en todas las páginas de la documentación
Reading DynamoDB well comes down to one distinction: Query targets a single partition and stays cheap at any scale, while Scan reads the whole table. Filters confuse people because they look like a WHERE clause but bill nothing like one.
This page shows efficient queries, correct pagination, where filters really apply, and the rare cases where a Scan is fine - with runnable code in both SDKs using the document interface.
Quick-reference recipe card - copy-paste ready.
# --- Python (boto3) ---
from boto3.dynamodb.conditions import Key, Attr
# Query one partition (key condition = efficient), then filter (post-read).
resp = table.query(
KeyConditionExpression=Key("pk").eq("CUSTOMER#c-1") & Key("sk").begins_with("ORDER#"),
FilterExpression=Attr("total").gt(20), # applied AFTER the read
ProjectionExpression="sk, total", # return only these attributes
ScanIndexForward=False, # newest first
)
print(resp["Items"])// --- TypeScript (AWS SDK v3) ---
import { QueryCommand } from "@aws-sdk/lib-dynamodb";
const resp = await doc.send(new QueryCommand({
TableName: "AppData",
KeyConditionExpression: "pk = :p AND begins_with(sk, :prefix)",
FilterExpression: "#t > :min", // applied AFTER the read
ProjectionExpression: "sk, #t", // return only these attributes
ExpressionAttributeNames: { "#t": "total" },
ExpressionAttributeValues: { ":p": "CUSTOMER#c-1", ":prefix": "ORDER#", ":min": 20 },
ScanIndexForward: false, // newest first
}));
console.log(resp.Items);When to reach for this:
ProjectionExpression to save bandwidth.Scan on hot paths - design a key or index to Query instead.Query one customer's orders newest-first, paginate through a large result set with LastEvaluatedKey, then contrast with a Scan that reads the whole table.
# --- Python (boto3) ---
import boto3
from boto3.dynamodb.conditions import Key, Attr
table = boto3.resource("dynamodb", region_name="us-east-1").Table("AppData")
# 1. Query with a key condition + sort-key range + reverse order.
resp = table.query(
KeyConditionExpression=Key("pk").eq("CUSTOMER#c-1") & Key("sk").begins_with("ORDER#"),
ScanIndexForward=False, # descending: newest first
Limit=50,
)
print([i["sk"] for i in resp["Items"]])
# 2. Paginate: keep passing LastEvaluatedKey until it is absent.
items, start_key = [], None
while True:
kwargs = {"KeyConditionExpression": Key("pk").eq("CUSTOMER#c-1")}
if start_key:
kwargs["ExclusiveStartKey"] = start_key
page = table.query(**kwargs)
items.extend(page["Items"])
start_key = page.get("LastEvaluatedKey")
if not start_key:
break
print("total items:", len(items))
# 3. Scan reads the WHOLE table; the filter runs after the read.
scanned = table.scan(FilterExpression=Attr("total").gt(100))
print("matched (but paid to read all):", len(scanned["Items"]))// --- TypeScript (AWS SDK v3) ---
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, QueryCommand, ScanCommand } from "@aws-sdk/lib-dynamodb";
const doc = DynamoDBDocumentClient.from(new DynamoDBClient({ region: "us-east-1" }));
// 1. Query with a key condition + sort-key range + reverse order.
const resp = await doc.send(new QueryCommand({
TableName: "AppData",
KeyConditionExpression: "pk = :p AND begins_with(sk, :prefix)",
ExpressionAttributeValues: { ":p": "CUSTOMER#c-1", ":prefix": "ORDER#" },
ScanIndexForward: false, // descending: newest first
Limit: 50,
}));
console.log((resp.Items ?? []).map((i) => i.sk));
// 2. Paginate: keep passing LastEvaluatedKey until it is absent.
const items: Record<string, unknown>[] = [];
let startKey: Record<string, unknown> | undefined = undefined;
do {
const page = await doc.send(new QueryCommand({
TableName: "AppData",
KeyConditionExpression: "pk = :p",
ExpressionAttributeValues: { ":p": "CUSTOMER#c-1" },
ExclusiveStartKey: startKey,
}));
items.push(...(page.Items ?? []));
startKey = page.LastEvaluatedKey;
} while (startKey);
console.log("total items:", items.length);
// 3. Scan reads the WHOLE table; the filter runs after the read.
const scanned = await doc.send(new ScanCommand({
TableName: "AppData",
FilterExpression: "#t > :min",
ExpressionAttributeNames: { "#t": "total" },
ExpressionAttributeValues: { ":min": 100 },
}));
console.log("matched (but paid to read all):", (scanned.Items ?? []).length);What this demonstrates:
Query needs a partition-key equality; sort-key conditions narrow within it efficiently.ScanIndexForward=False returns items in descending sort order without extra work.LastEvaluatedKey back as ExclusiveStartKey.Scan reads and meters every item; its FilterExpression only trims what comes back.This is the single most important idea on the page.
A KeyConditionExpression operates on the partition key (equality only) and the sort key (equality, comparison, begins_with, between). DynamoDB uses it to find items, so you are metered only on the items it matches. It is where efficiency lives.
A FilterExpression runs on non-key attributes after DynamoDB has already read and metered the items. It reduces the payload returned to you but never the read cost. Filtering a million items down to ten still bills for a million items' worth of reads. Treat filters as a convenience for trimming an already-cheap result, never as a way to make an expensive read cheap.
DynamoDB returns at most 1 MB of data per read call. If more matches exist, the response includes a LastEvaluatedKey. Pass it back as ExclusiveStartKey to get the next page, and stop when it is absent. A Limit caps items per page but does not change this loop. Note that Limit applies before filtering, so a filtered page can come back with fewer items than Limit yet still have a LastEvaluatedKey.
ProjectionExpression asks DynamoDB to return only named attributes, cutting network bytes (though not read-capacity units, which are based on item size read). Use #name placeholders for reserved words. Add ConsistentRead=True to a base-table or LSI Query when you must see the latest write; GSIs are always eventually consistent.
When a Scan is genuinely required (a migration, an export, a small table), you can parallelize it by splitting the table into segments and scanning each concurrently.
# --- Python (boto3) ---
# Worker 0 of 4: each worker scans a disjoint segment concurrently.
page = table.scan(Segment=0, TotalSegments=4)
print(len(page["Items"]))// --- TypeScript (AWS SDK v3) ---
import { ScanCommand } from "@aws-sdk/lib-dynamodb";
// Worker 0 of 4: each worker scans a disjoint segment concurrently.
const page = await doc.send(new ScanCommand({ TableName: "AppData", Segment: 0, TotalSegments: 4 }));
console.log((page.Items ?? []).length);FilterExpression runs after the read and bills for every item scanned. Fix: move the condition into a KeyConditionExpression or a GSI.LastEvaluatedKey/ExclusiveStartKey until it is absent.Limit surprises with filters. Limit counts items examined before filtering, so a filtered page may return fewer rows than Limit. Fix: keep paginating while LastEvaluatedKey is present.Scan on a hot path. Scans read the entire table and slow down as it grows. Fix: design a key or index so the read is a Query.status, name, size, ttl, and others are reserved. Fix: use ExpressionAttributeNames placeholders.ConsistentRead=True when freshness matters.| Alternative | Use When | Don't Use When |
|---|---|---|
| Query (this page) | You have the partition key and want its items | You need data across many partition keys |
| Query on a GSI | A second access pattern on non-key attributes | The base key already answers the query |
| Scan | Small tables, migrations, one-off exports | Any latency- or cost-sensitive request path |
| Parallel Scan | A large full-table pass you must do | A targeted read a Query could serve |
PartiQL SELECT | You prefer SQL-like syntax for the same ops | You need the finest control over capacity |
Query reads only items under one partition key you supply and is efficient at any scale. Scan reads every item in the table (or index) and its cost grows with the data, regardless of how many items you keep.
No. Filters are applied after DynamoDB reads and meters the items, so they reduce the payload returned but not the capacity consumed. To reduce cost, narrow with a KeyConditionExpression or an index.
Each read returns up to 1 MB. If more results exist, the response includes a LastEvaluatedKey. Pass it back as ExclusiveStartKey on the next call and repeat until the response omits it.
Limit counts items examined before the filter runs. If a FilterExpression removes some, the page returns fewer than Limit even though more matching items may exist - keep paginating on LastEvaluatedKey.
Set ScanIndexForward to false on a Query. Items are stored ascending by sort key, so this returns them in descending order without any client-side sorting.
It limits the attributes returned to only those you name, reducing network payload. It does not reduce read-capacity units, which are based on the size of the item read, not the size returned.
For small tables, one-off maintenance, migrations, or full exports where reading everything is the intent. For large or hot tables, use a parallel Scan if you must, but prefer designing a Query-able key or index.
Yes. Pass IndexName and a KeyConditionExpression on the index's keys. The only difference is that GSIs are always eventually consistent, so you cannot request a strongly consistent read on them.
Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).
Revisado por Chris St. John·Última actualización: 23 jul 2026