DynamoDB Scan in Node.js (AWS SDK v3)

Il do/while qui sotto non è programmazione difensiva. Una pagina di uno Scan filtrato può tornare con un array Items vuoto e avere comunque altra tabella davanti, quindi fermarsi alla prima risposta è il modo in cui uno scan riporta zero corrispondenze su una tabella che ne ha. Query vs Scan spiega quando evitare del tutto l'operazione.

Codice

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

Due pagine vuote, 284,5 unità di lettura, 8 Item

La fixture è di 600 canzoni da circa 3,9 KB ciascuna, di cui esattamente 8 hanno Year >= 2010, e stanno in fondo all'ordinamento. Ecco cosa riceve davvero il loop qui sopra:

Round trip	`Items.length`	`ScannedCount`	Unità di lettura	`LastEvaluatedKey`
1	0	271	128,5	presente
2	0	271	128,5	presente
3	8	58	27,5	assente

Due pagine consecutive non restituiscono nulla e costano 128,5 unità di lettura ciascuna. Il codice che fa if (!response.Items.length) return riporta una tabella vuota. Il riferimento dell'API enuncia la regola senza giri di parole: "a scan result can result in no items meeting the criteria and the Count will result in zero", e separatamente che "a FilterExpression is applied after the items have already been read; the process of filtering does not consume any additional read capacity units".

Leggi quella seconda frase come la legge la tua fattura. Il filtro è gratis, e tutto ciò che ha scartato non lo è: 284,5 unità di lettura per consegnare 8 Item, la stessa bolletta che pagheresti senza alcun filtro.

Misurato il 2026-07-28 su DynamoDB Local (amazon/dynamodb-local) con @aws-sdk/client-dynamodb 3.1095.0 su node v24.18.0. I conteggi e la capacità sono i campi di risposta del motore stesso.

Spiegazione

ExclusiveStartKey: lastEvaluatedKey è undefined alla prima passata. Il serializzatore v3 scarta i membri undefined, quindi un solo object literal copre la prima richiesta e tutte le successive. Passare {} invece fallisce con ValidationException: The provided starting key is invalid.
response.Items ?? [] sta facendo un lavoro vero. Combinalo con la tabella qui sopra: il nullish coalescing tiene onesto l'accumulatore sulle pagine che non hanno trovato nulla, e il while tiene vivo il loop oltre quelle.
#filter0 non è decorazione. Year è nella lista delle parole riservate di AWS, e usarlo senza alias restituisce ValidationException: Invalid FilterExpression: Attribute name is a reserved keyword; reserved keyword: Year.
Limit conta gli Item letti, non quelli restituiti. Con questo filtro, Limit: 10 produce Count: 0 e ScannedCount: 10. È una manopola di throttling per i picchi di capacità, non un modo per chiedere dieci risultati.
Segment / TotalSegments distribuiscono uno scan dell'intera tabella tra più worker. Questo divide il tempo reale, non il costo — si spendono le stesse 284,5 unità, solo più in fretta e più in parallelo.

Quanto costa su una tabella vera

284,5 unità di lettura per 8 Item è la forma del problema, e scala linearmente con la tabella, non con il risultato. Prima di mandare in produzione uno scan filtrato su un percorso critico, calcola il prezzo della lettura completa alla tua dimensione degli Item e al tuo traffico nel calcolatore dei prezzi DynamoDB, poi confrontalo con un GSI che trasforma lo stesso pattern di accesso in una Query.

Per esplorare le tabelle in una GUI, con griglie di risultati filtrate e paginate, scarica DynoTable invece di scansionare alla cieca da uno script.

Guide correlate

Query vs Scan — quando (raramente) uno Scan è giustificato.
Perché il mio Scan DynamoDB è lento e costoso? — il modello di costo e come evitarlo.
DynamoDB ProvisionedThroughputExceededException — cosa fa uno scan dell'intera tabella alla capacità di una tabella con provisioning.
DynamoDB ThrottlingException — l'altro throttle, e come lo gestisce il backoff esponenziale.