DynamoDB Scan in Node.js (AWS SDK v3)

Das do/while unten ist kein defensives Programmieren. Eine gefilterte Scan-Seite kann mit einem leeren Items-Array zurückkommen und trotzdem noch Tabelle übrig haben — bei der ersten Antwort aufzuhören ist also genau die Art, wie ein Scan null Treffer auf einer Tabelle meldet, die welche hat. Query vs. Scan behandelt, wann du die Operation ganz vermeiden solltest.

Code

import {DynamoDBClient, ScanCommand} from '@aws-sdk/client-dynamodb';

const client = new DynamoDBClient({region: 'us-east-1'});

const items = [];
let lastEvaluatedKey;

do {
  const response = await client.send(
    new ScanCommand({
      TableName: 'Music',
      FilterExpression: '#filter0 >= :filterValue0',
      ExpressionAttributeNames: {
        '#filter0': 'Year'
      },
      ExpressionAttributeValues: {
        ':filterValue0': {N: '2010'}
      },
      ExclusiveStartKey: lastEvaluatedKey
    })
  );

  items.push(...(response.Items ?? []));
  lastEvaluatedKey = response.LastEvaluatedKey;
} while (lastEvaluatedKey);

console.log(`Matched ${items.length} items`);

Zwei leere Seiten, 284,5 Leseeinheiten, 8 Items

Das Fixture besteht aus 600 Songs von je rund 3,9 KB, von denen genau 8 Year >= 2010 haben — und die sortieren zuletzt. Das hier bekommt die Schleife oben tatsächlich:

Zwei aufeinanderfolgende Seiten liefern nichts und kosten je 128,5 Leseeinheiten. Code, der if (!response.Items.length) return macht, meldet eine leere Tabelle. Die API-Referenz nennt die Regel klar: "a scan result can result in no items meeting the criteria and the Count will result in zero" — und separat, dass "a FilterExpression is applied after the items have already been read; the process of filtering does not consume any additional read capacity units".

Lies den zweiten Satz so, wie deine Rechnung ihn liest. Der Filter ist kostenlos, und alles, was er verworfen hat, ist es nicht: 284,5 Leseeinheiten, um 8 Items zu liefern — dieselbe Rechnung, die du ganz ohne Filter zahlen würdest.

Am 2026-07-28 gegen DynamoDB Local (amazon/dynamodb-local) mit @aws-sdk/client-dynamodb 3.1095.0 auf node v24.18.0 gemessen. Die Zähler und die Kapazität sind die Antwortfelder der Engine selbst.

Erklärung

• ExclusiveStartKey: lastEvaluatedKey ist im ersten Durchlauf undefined. Der v3-Serializer lässt undefined-Member weg, ein einziges Objektliteral deckt also die erste Anfrage und jede Folgeanfrage ab. Stattdessen {} zu übergeben scheitert mit ValidationException: The provided starting key is invalid.
• response.Items ?? [] leistet echte Arbeit. Kombiniere es mit der Tabelle oben: Der Nullish-Coalescing-Operator hält den Akkumulator auf den Seiten ehrlich, die nichts getroffen haben, und das while hält die Schleife darüber hinaus am Leben.
• #filter0 ist keine Dekoration. Year steht auf AWS' Liste reservierter Wörter, und ohne Alias verwendet liefert es ValidationException: Invalid FilterExpression: Attribute name is a reserved keyword; reserved keyword: Year.
• Limit zählt gelesene Items, nicht zurückgegebene. Mit diesem Filter ergibt Limit: 10 ein Count: 0 und ScannedCount: 10. Es ist ein Drossel-Regler für Kapazitätsspitzen, kein Weg, um zehn Ergebnisse zu bitten.
• Segment / TotalSegments verteilen einen Full-Table-Scan auf Worker. Das teilt die Laufzeit, nicht die Kosten — es werden dieselben 284,5 Einheiten ausgegeben, nur schneller und nebenläufiger.

Was das auf einer echten Tabelle kostet

284,5 Leseeinheiten für 8 Items ist die Form des Problems, und sie skaliert linear mit der Tabelle, nicht mit dem Ergebnis. Bevor du einen gefilterten Scan auf einen heißen Pfad schickst, bepreise den Full-Table-Read mit deiner Item-Größe und deinem Traffic im DynamoDB-Preisrechner und vergleiche ihn dann mit einem GSI, der dasselbe Zugriffsmuster in ein Query verwandelt.

Um Tabellen in einer GUI zu erkunden, mit gefilterten und paginierten Ergebnis-Grids, lade DynoTable herunter, statt blind aus einem Skript 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 du es vermeidest.
• 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
• ScanCommand — AWS SDK for JavaScript v3 Reference
• Scanning tables — Amazon DynamoDB Developer Guide
• Capacity unit consumption — Amazon DynamoDB Developer Guide