DynamoDB Query in Node.js (AWS SDK v3)

Eine vollständige Query in AWS SDK v3 ist die do/while-Schleife unten, nicht das einzelne client.send(), das die meisten Snippets zeigen: Eine Seite ist bei 1 MB gedeckelt, und der Rest der Partition kommt nur an, wenn du LastEvaluatedKey zurückgibst. Siehe Query vs. Scan dazu, wann Query überhaupt das richtige Lesen ist.

Code

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

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

const items = [];
let lastEvaluatedKey;

do {
  const response = await client.send(
    new QueryCommand({
      TableName: 'Music',
      KeyConditionExpression: '#hashKey = :hashKeyValue AND begins_with(#rangeKey, :rangeKeyValue)',
      ExpressionAttributeNames: {
        '#hashKey': 'Artist',
        '#rangeKey': 'SongTitle'
      },
      ExpressionAttributeValues: {
        ':hashKeyValue': {S: 'Arturo Sandoval'},
        ':rangeKeyValue': {S: 'C'}
      },
      ExclusiveStartKey: lastEvaluatedKey
    })
  );

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

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

Was die Schleife tatsächlich tut

Gegen ein Fixture aus 600 Songs, jeder ~3,9 KB und alle unter Artist = "Arturo Sandoval", schickt die Schleife oben drei Requests:

Niemand hat 271 konfiguriert. Da war 1 MB erschöpft — die Seitengrenze wandert also, sobald sich deine Item-Größe ändert. Eine Partition, die heute einmal blättert, blättert nach dem Hinzufügen eines Attributs zweimal, und Code, der response.Items aus einem einzelnen send() liest, gibt stillschweigend 271 von 600 Songs zurück, ohne Fehler.

Ergänze nun Limit: 10 und eine FilterExpression auf Year an derselben Query:

Count: 0   ScannedCount: 10   ConsumedCapacity: 5   LastEvaluatedKey: set

Zehn Items ausgewertet, null zurückgegeben — und der Request hat trotzdem Lesekapazität gekostet. Limit begrenzt, was DynamoDB liest, und der Filter läuft danach; ein Limit, das „gib mir 10 Ergebnisse" meinen soll, gibt dir also zwischen 0 und 10.

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

Erklärung

• ExclusiveStartKey: lastEvaluatedKey ist im ersten Durchlauf undefined, und das ist Absicht: Der v3-Serializer verwirft undefined-Member, dasselbe Objektliteral funktioniert also für den ersten Request und jeden Folge-Request. {} einzusetzen — die naheliegende Vermutung für „fang von vorn an" — scheitert mit ValidationException: The provided starting key is invalid.
• @aws-sdk/client-dynamodb marshallt nie für dich. Werte gehen als {S: 'Arturo Sandoval'} hinein und Items kommen genauso zurück. Das ist der Preis dafür, den DocumentClient nicht hereinzuziehen; wenn du lieber schlichte JS-Objekte schreiben willst, ist @aws-sdk/lib-dynamodb der Wrapper, zu dem du greifst.
• Zahlen überstehen den Roundtrip als Strings. {N: '9007199254740993'} mit unmarshall aus @aws-sdk/util-dynamodb zu entpacken liefert ein JS-bigint, keine verlustbehaftete number; übergib {wrapNumbers: true} und du bekommst stattdessen {value: '9007199254740993'}. So oder so: Wende Number() nie auf ein DynamoDB-N an, dessen Größe du nicht geprüft hast.
• KeyConditionExpression nimmt eine Gleichheit auf dem Partition Key plus höchstens eine Sort-Key-Bedingung (=, <, <=, >, >=, BETWEEN, begins_with). Alles andere gehört in eine FilterExpression, die nach dem Lesen läuft.
• ScanIndexForward: false kehrt die Sort-Key-Reihenfolge um; aufsteigend ist der Standard. IndexName schaltet denselben Command auf einen Sekundärindex um.

Mach es visuell

Der DynamoDB Query Builder gibt diese gesamte Form aus — Key Condition, Name- und Value-Maps sowie die LastEvaluatedKey-Schleife — als lauffähiges SDK-v3-Programm, damit die Pagination nicht der Teil ist, den du vergisst.

Um Abfragen gegen echte Tabellen in einer GUI auszuführen, mit einem Key-Condition-Formular und einem paginierten Ergebnis-Grid, lade DynoTable herunter.

Verwandte Leitfäden

• Query vs. Scan — warum Query der richtige Standard ist.
• Key Condition Expressions — jeder zulässige 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, wie contains oder eine zweite Sort-Key-Bedingung.

Referenzen

• Query — Amazon DynamoDB API Reference
• QueryCommand — AWS SDK for JavaScript v3 Reference
• Querying tables — Amazon DynamoDB Developer Guide
• Key condition expressions for Query — Amazon DynamoDB Developer Guide