DynamoDB GetItem en Node.js (AWS SDK v3)

L'AWS SDK v3 te donne deux façons de lire un élément : GetItemCommand sur un DynamoDBClient, qui parle le format du protocole ({S: '...'}), ou GetCommand sur un DynamoDBDocumentClient, qui prend et renvoie du JavaScript ordinaire.

L'exemple utilise le client bas niveau. Ces enveloppes sont ce à quoi ressemble réellement l'encodage attribute-value sur le réseau, et ce que les messages d'erreur te recrachent. Dans les deux cas, la requête a besoin de la clé primaire complète.

Code

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

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

const command = new GetItemCommand({
  TableName: 'Music',
  Key: {
    Artist: {S: 'Arturo Sandoval'},
    SongTitle: {S: 'Cubano Chant'}
  },
  ProjectionExpression: '#proj0, #proj1, #proj2, #proj3',
  ExpressionAttributeNames: {
    '#proj0': 'Artist',
    '#proj1': 'SongTitle',
    '#proj2': 'AlbumTitle',
    '#proj3': 'Year'
  }
});

const response = await client.send(command);

if (!response.Item) {
  console.log('Item not found');
} else {
  console.log(response.Item);
}

Explication

send(command), pas client.getItem() — DynamoDBClient n'expose que send. La classe agrégée DynamoDB du même package porte bien une méthode getItem si tu veux des appels à la manière du SDK v2, au prix de tirer toutes les commandes dans ton bundle.
Un échec de correspondance, c'est undefined, pas une erreur — response.Item est simplement absent, et l'appel se résout quand même. response.$metadata arrive toujours : tester la véracité de la réponse elle-même ne t'apprend donc rien.
unmarshall choisit le type de nombre selon l'ordre de grandeur — un {N: …} dans la plage des entiers sûrs revient en number, tout ce qui est en dehors en BigInt, et un grand non-entier lève can't be converted to BigInt. Passe {wrapNumbers: true} à unmarshall depuis @aws-sdk/util-dynamodb et chaque nombre arrive en NumberValue à la place, pour que ce soit toi qui décides de la conversion.
Les alias #proj sont porteurs — Year figure sur la liste des mots réservés d'AWS : une ProjectionExpression qui le nomme directement est donc rejetée. Aliaser chaque nom, comme ci-dessus, est le choix sûr par défaut. Ça réduit la réponse, pas le coût de la lecture (pourquoi).
ConsumedCapacity est optionnel — ajoute ReturnConsumedCapacity: 'TOTAL' et la réponse indique ce que cette lecture a réellement coûté : 0,5 unité de capacité pour une lecture à terme d'un élément de moins de 4 KB, 1,0 dès que tu ajoutes ConsistentRead: true (le compromis).
Hisse le client — construis DynamoDBClient une seule fois au niveau du module. En construire un par requête, ou à l'intérieur d'un handler Lambda, jette le pool de connexions et les identifiants résolus à chaque appel.

Le faire visuellement

DynoTable affiche les éléments comme des lignes ordinaires plutôt que comme des maps attribute-value, et exporte la requête derrière la grille sous forme de programme SDK v3 exécutable. Télécharge DynoTable.

Guides liés

Query vs Scan — quand un simple GetItem bat une Query.
Comment fonctionnent les clés de partition DynamoDB — pourquoi GetItem a besoin de la clé complète.
DynamoDB ResourceNotFoundException — la première erreur habituelle ici : mauvais nom de table ou mauvaise Région.
"The provided key element does not match the schema" — la clé que tu passes ne correspond pas au schéma de clé de la table.

Références

Dernière vérification le 2026-07-28 par rapport à la documentation officielle AWS liée ci-dessus.