DynamoDB Query in Python (boto3)

boto3s query-Paginator ist der Grund, warum diese Seite kurz ist: Er versteckt LastEvaluatedKey vollständig. Er versteckt außerdem eine Zahl, die du wahrscheinlich haben wolltest — und genau das solltest du wissen, bevor du ihm vertraust. Wann du überhaupt zu query greifen solltest, steht in Query vs. Scan.

Code

import boto3

client = boto3.client("dynamodb")

paginator = client.get_paginator("query")

items = []
for page in paginator.paginate(
    TableName="Music",
    KeyConditionExpression="#hashKey = :hashKeyValue AND begins_with(#rangeKey, :rangeKeyValue)",
    ExpressionAttributeNames={"#hashKey": "Artist", "#rangeKey": "SongTitle"},
    ExpressionAttributeValues={":hashKeyValue": {"S": "Arturo Sandoval"}, ":rangeKeyValue": {"S": "C"}},
):
    items.extend(page["Items"])

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

Der Paginator addiert deine Rechnung nicht

Gegen ein Fixture aus 600 Songs, jeder ~3,9 KB und alle unter Artist = "Arturo Sandoval", liefert die Schleife drei Seiten: 271, 271 und 58 Items, die 128,5, 128,5 und 27,5 Leseeinheiten kosten. Frag denselben Paginator nach einem zusammengeführten Ergebnis, und du bekommst das hier:

build_full_result() -> Items 600  Count 600  ScannedCount 600
                       ConsumedCapacity.CapacityUnits 128.5

Count und ScannedCount wurden summiert. ConsumedCapacity nicht — das ist der Wert der ersten Seite, und der echte Gesamtwert war 284,5. botocores DynamoDB-Paginator-Konfiguration sagt deutlich, warum: Count und ScannedCount sind als Result Keys gelistet, ConsumedCapacity als Non-Aggregate Key. Wenn du Kapazität aus build_full_result() loggst, meldest du einen Read über eine ganze Partition um mehr als die Hälfte zu niedrig.

Die Pro-Seite-Dicts in der for page in paginator.paginate(...)-Schleife oben sind rohe Antworten — page["ConsumedCapacity"]["CapacityUnits"] selbst zu summieren ergibt also die ehrlichen 284,5.

Das Limit, das dich 58 zusätzliche Roundtrips kostet

Limit ist ein gültiger query-Parameter, paginate() nimmt ihn also an — und es ist nicht der Parameter, den Python-Nutzer erwarten:

paginate(..., Limit=10)  ->  61 pages, 10 items each
paginate(...)            ->   3 pages

Es deckelt Items pro Anfrage, nicht insgesamt — der Paginator macht also brav 61 HTTP-Aufrufe, um dieselben 600 Items zu holen. Um die Gesamtzahl zu deckeln, nimm PaginationConfig={"MaxItems": 10}; PaginationConfig["PageSize"] ist der Regler, der auf Limit abbildet.

Am 2026-07-28 gegen DynamoDB Local (amazon/dynamodb-local) mit boto3 1.43.58 auf CPython 3.14.6 gemessen.

Erklärung

• Der Client spricht in beide Richtungen DynamoDB-JSON. Werte gehen als {"S": "Arturo Sandoval"} hinein und Year kommt als {"N": "1994"} zurück. Die Resource-API (boto3.resource("dynamodb").Table(...).query) konvertiert in beide Richtungen und reicht dir Decimal('1994') — was für Geldbeträge richtig ist und beim ersten Mal überrascht, wenn es sich weigert, zu einem float addiert zu werden.
• Key("Artist").eq(...) gehört ausschließlich zur Resource-API. Gibst du es dem Client, wirft er, bevor die Anfrage rausgeht: ParamValidationError: Invalid type for parameter KeyConditionExpression ... valid types: <class 'str'>. Der Client will den Expression-String, den diese Seite baut.
• Die Key Condition ist eine Gleichheit plus höchstens ein Sort-Key-Vergleich (=, <, <=, >, >=, BETWEEN, begins_with). Alles andere gehört in eine FilterExpression, die boto3 direkt durchreicht und die DynamoDB nach dem Read anwendet. ScanIndexForward=False dreht die Reihenfolge um, IndexName="..." richtet die Abfrage auf einen Index.

Mach es visuell

Der DynamoDB Expression Builder schreibt die Key Condition und die typisierte ExpressionAttributeValues-Map als boto3-fertiges Python — genau den Teil, der schiefgeht, wenn du {"N": 2010} statt {"N": "2010"} tippst.

Um dieselbe Abfrage aus einem Key-Condition-Formular gegen deine eigenen Tabellen zu richten und die Ergebnisse in einem paginierten Grid zu lesen, lade DynoTable herunter.

Verwandte Leitfäden

• Query vs. Scan — warum query der richtige Standard ist.
• Key Condition Expressions — jeder erlaubte Partition-/Sort-Key-Operator.
• „Query condition missed key schema element" — die Key Condition benennt das falsche Attribut oder überspringt den Partition Key.
• „Query key condition not supported" — ein Operator, den die Key Condition nicht nutzen kann, etwa contains oder eine zweite Sort-Key-Bedingung.

Referenzen

• Query — Amazon DynamoDB API Reference
• query — Boto3 DynamoDB.Client Reference
• Query paginator — Boto3 DynamoDB Reference
• Querying tables — Amazon DynamoDB Developer Guide
• Key condition expressions for Query — Amazon DynamoDB Developer Guide