Query DynamoDB en Node.js (AWS SDK v3)

Une Query complète en AWS SDK v3, c'est le do/while ci-dessous, pas le simple client.send() que montrent la plupart des extraits : une page plafonne à 1 Mo, et le reste de la partition n'arrive que si tu réinjectes LastEvaluatedKey. Voir Query vs Scan pour savoir si Query est seulement la bonne lecture.

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`);

Ce que la boucle fait vraiment

Sur un jeu de 600 morceaux d'environ 3,9 Ko chacun, tous sous Artist = "Arturo Sandoval", la boucle ci-dessus envoie trois requêtes :

Aller-retour	`Count`	`ScannedCount`	Unités de lecture	`LastEvaluatedKey`
1	271	271	128,5	présente
2	271	271	128,5	présente
3	58	58	27,5	absente

Personne n'a configuré 271. C'est là que le 1 Mo s'est épuisé : la frontière de page bouge donc dès que la taille de tes éléments bouge. Une partition qui pagine une fois aujourd'hui paginera deux fois après l'ajout d'un attribut, et du code qui lit response.Items d'un seul send() renvoie silencieusement 271 morceaux sur 600, sans la moindre erreur.

Ajoute maintenant Limit: 10 et une FilterExpression sur Year à la même requête :

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

Dix éléments évalués, zéro renvoyé, et la requête a quand même coûté de la capacité de lecture. Limit borne ce que DynamoDB lit, et le filtre s'exécute après : un Limit choisi pour dire « donne-moi 10 résultats » t'en donne entre 0 et 10.

Mesuré le 2026-07-28 sur DynamoDB Local (amazon/dynamodb-local) avec @aws-sdk/client-dynamodb 3.1095.0 sur node v24.18.0. Les compteurs et la capacité sont les champs de réponse du moteur lui-même.

Explication

ExclusiveStartKey: lastEvaluatedKey vaut undefined au premier passage, et c'est délibéré : le sérialiseur v3 supprime les membres undefined, donc le même littéral d'objet convient à la première requête comme à toutes les suivantes. Y substituer {} — la supposition évidente pour « commence au début » — échoue avec ValidationException: The provided starting key is invalid.
@aws-sdk/client-dynamodb ne marshalle jamais pour toi. Les valeurs entrent sous la forme {S: 'Arturo Sandoval'} et les éléments reviennent pareil. C'est le prix à payer pour ne pas embarquer le DocumentClient ; si tu préfères écrire des objets JS ordinaires, @aws-sdk/lib-dynamodb est le wrapper à prendre.
Les nombres survivent à l'aller-retour sous forme de chaînes. Démarshaller {N: '9007199254740993'} avec unmarshall de @aws-sdk/util-dynamodb renvoie un bigint JS, pas un number lossy ; passe {wrapNumbers: true} et tu obtiens {value: '9007199254740993'} à la place. Dans tous les cas, ne fais pas Number() sur un N DynamoDB dont tu n'as pas vérifié la taille.
KeyConditionExpression prend une égalité sur la clé de partition plus au plus une condition sur la clé de tri (=, <, <=, >, >=, BETWEEN, begins_with). Tout le reste appartient à une FilterExpression, qui s'exécute après la lecture.
ScanIndexForward: false inverse l'ordre de la clé de tri ; l'ordre croissant est la valeur par défaut. IndexName bascule la même commande sur un index secondaire.

Le faire visuellement

Le constructeur de requêtes DynamoDB émet toute cette forme — condition de clé, maps de noms et de valeurs, et la boucle LastEvaluatedKey — sous forme de programme SDK v3 exécutable, pour que la pagination ne soit pas la partie que tu oublies.

Pour lancer des requêtes sur de vraies tables dans une interface graphique, avec un formulaire de condition de clé et une grille de résultats paginée, télécharge DynoTable.

Guides liés

Query vs Scan — pourquoi Query est le bon choix par défaut.
Les expressions de condition de clé — chaque opérateur légal sur les clés de partition et de tri.
"Query condition missed key schema element" — la condition de clé nomme le mauvais attribut ou saute la clé de partition.
"Query key condition not supported" — un opérateur que la condition de clé ne peut pas utiliser, comme contains ou une deuxième condition sur la clé de tri.