DynamoDB Scan mit der AWS CLI

aws dynamodb scan paginiert automatisch — praktisch, und zugleich der Grund, warum die eine Zahl, an der du den Schaden ablesen würdest, standardmäßig falsch ist. Siehe Query vs. Scan dazu, wann man die Operation ganz vermeiden sollte.

Code

aws dynamodb scan \
  --table-name 'Music' \
  --filter-expression '#filter0 >= :filterValue0' \
  --expression-attribute-names '{"#filter0":"Year"}' \
  --expression-attribute-values '{":filterValue0":{"N":"2010"}}'

--return-consumed-capacity meldet eine Seite, nicht den Scan

Das Fixture besteht aus 600 Songs von je rund 3,9 KB, von denen 8 passen. Füge diesem Befehl --return-consumed-capacity TOTAL hinzu, und die CLI gibt aus:

{ "Count": 8, "ScannedCount": 600, "CU": 128.5 }

Der Scan kostete in Wahrheit 284,5 Read-Einheiten über drei Seiten. Count und ScannedCount wurden über alle drei summiert; ConsumedCapacity wurde von der ersten genommen und der Rest weggeworfen. Das ist weniger ein Bug als eine deklarierte Regel — botocores DynamoDB-Paginator-Konfiguration führt Count und ScannedCount als Result Keys und ConsumedCapacity als Non-Aggregate Key.

Verräterisch ist, dass sich die Zahl bewegt, obwohl die Arbeit gleich bleibt. Dieselbe Tabelle, dieselben 600 gelesenen Items, ein zusätzliches Flag:

--page-size 50  ->  { "Count": 8, "ScannedCount": 600, "CU": 24.0 }

Wenn du eine Tabelle anhand eines CLI-Scans dimensionierst, summiere die Seiten selbst über --page-size plus --starting-token, oder lies die Kapazität aus CloudWatch.

--max-items stoppt den Scan nicht

--max-items 3 liest sich wie eine billige Stichprobe. Ist es nicht:

--max-items 3  ->  { "Count": 8, "ScannedCount": 600 }

Die CLI forderte weiter Seiten an, bis sie genug Treffer hatte — was bei einem selektiven Filter die gesamte Tabelle bedeutete — und kürzte danach die ausgegebene Liste. Ihr eigenes Resume-Token sagt das laut und deutlich:

{"ExclusiveStartKey": {"Artist": {"S": "Arturo Sandoval"},
 "SongTitle": {"S": "Cubano Chant 0541"}}, "boto_truncate_amount": 3}

boto_truncate_amount ist ein clientseitiger Zähler. Um zu begrenzen, was DynamoDB liest, nimm --page-size — das setzt das Limit der API für jede zugrunde liegende Anfrage — und setze mit --starting-token fort:

aws dynamodb scan \
  --table-name 'Music' \
  --page-size 500 \
  --max-items 100 \
  --starting-token "$NEXT_TOKEN"

Am 2026-07-28 gegen DynamoDB Local (amazon/dynamodb-local) mit aws-cli/2.36.9 gemessen. Das JSON oben ist die Ausgabe der CLI selbst, mit --query auf Breite umgeformt.

Erklärung

• --filter-expression läuft nach dem Read, es verkleinert also die Ausgabe und nicht die Rechnung. #filter0 aliast Year über --expression-attribute-names, weil Year ein reserviertes Wort ist.
• --expression-attribute-values will die Zahl doppelt gequotet: Shell-Quotes um das JSON, und den Wert als JSON-String. Lässt du die inneren Quotes weg, erreicht das DynamoDB nie — die CLI lehnt es lokal ab, mit Invalid type for parameter ExpressionAttributeValues.:v.N, value: 2010, type: <class 'int'>, valid types: <class 'str'>.
• --page-size ist das Flag, das den API-Aufruf ändert. Es wird zum Limit jeder zugrunde liegenden Anfrage und deckelt die pro Seite ausgewerteten Items. Der Rest der Paginierungsfamilie (--max-items, --starting-token) ist die CLI, die ihre eigene Ausgabe verwaltet.
• Parallel Scan braucht --segment N --total-segments M pro Worker, und jeder Worker führt sein eigenes --starting-token. Das kauft dir Laufzeit, keine Kapazität.

Mach es visuell

Der DynamoDB Expression Builder gibt den Filter und beide JSON-Maps bereits für die Shell escaped aus — das räumt die Quoting-Schicht weg, an der CLI-Expressions scheitern, bevor DynamoDB sie überhaupt sieht.

Um Tabellen in einer GUI zu erkunden, mit gefilterten und paginierten Grids, lade DynoTable herunter, statt blind aus dem Terminal zu scannen.

Verwandte Leitfäden

• Query vs. Scan — wann ein scan (selten) gerechtfertigt ist.
• Warum ist mein DynamoDB-Scan langsam und teuer? — das Kostenmodell und wie man es umgeht.
• DynamoDB ProvisionedThroughputExceededException — was ein Full-Table-Scan mit der Kapazität einer provisionierten Tabelle macht.
• DynamoDB ThrottlingException — die andere Drosselung und wie exponentielles Backoff sie abfängt.

Referenzen

• Scan — Amazon DynamoDB API Reference
• scan — AWS CLI Command Reference
• Using the pagination options in the AWS CLI — AWS CLI User Guide
• Scanning tables — Amazon DynamoDB Developer Guide