DynamoDB GetItem in Node.js (AWS SDK v3)

AWS SDK v3 ti dà due modi per leggere un singolo Item: GetItemCommand su un DynamoDBClient, che parla il formato wire ({S: '...'}), oppure GetCommand su un DynamoDBDocumentClient, che accetta e restituisce JavaScript semplice.

L'esempio usa il client di basso livello. Quei wrapper sono l'aspetto reale della codifica attribute-value sul wire, ed è quello che i messaggi di errore ti citano. In entrambi i casi la richiesta ha bisogno della chiave primaria completa.

Codice

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

Spiegazione

send(command), non client.getItem() — DynamoDBClient espone solo send. La classe aggregata DynamoDB dello stesso package porta invece un metodo getItem, se vuoi chiamate in stile SDK v2, al prezzo di trascinare ogni comando nel tuo bundle.
Un mancato riscontro è undefined, non un errore — response.Item è semplicemente assente, e la chiamata si risolve comunque. response.$metadata arriva sempre, quindi la truthiness della risposta stessa non ti dice nulla.
unmarshall sceglie il tipo numerico in base alla grandezza — un {N: …} dentro l'intervallo dei safe integer torna come number, tutto ciò che sta fuori come BigInt, e un numero non intero grande solleva can't be converted to BigInt. Passa {wrapNumbers: true} a unmarshall da @aws-sdk/util-dynamodb e ogni numero arriva invece come NumberValue, così decidi tu la conversione.
Gli alias #proj sono portanti — Year è nella lista delle parole riservate di AWS, quindi una ProjectionExpression che lo nomina direttamente viene rifiutata. Fare l'alias di ogni nome, come sopra, è il default sicuro. Riduce la risposta, non il costo della lettura (perché).
ConsumedCapacity è opt-in — aggiungi ReturnConsumedCapacity: 'TOTAL' e la risposta riporta quanto è costata davvero questa lettura: 0,5 unità di capacità per una lettura a coerenza eventuale di un Item sotto i 4 KB, 1,0 non appena aggiungi ConsistentRead: true (il compromesso).
Porta il client fuori dall'handler — costruisci DynamoDBClient una volta sola a livello di modulo. Crearne uno per richiesta, o dentro un handler Lambda, butta via il pool di connessioni e le credenziali risolte a ogni chiamata.

Fallo visivamente

DynoTable mostra gli Item come normali righe invece che come mappe attributo-valore, ed esporta la query dietro la griglia come programma SDK v3 eseguibile. Scarica DynoTable.

Guide correlate

Query vs. Scan — quando un singolo GetItem batte una Query.
Come funzionano le chiavi di partizione di DynamoDB — perché GetItem ha bisogno della chiave completa.
DynamoDB ResourceNotFoundException — il primo errore tipico qui: nome tabella o regione sbagliati.
"The provided key element does not match the schema" — la chiave che passi non corrisponde allo schema di chiave della tabella.

Riferimenti

Ultima verifica 2026-07-28 rispetto alla documentazione ufficiale AWS collegata sopra.