DynamoDB Scan in Node.js (AWS SDK v3)

Scan reads every item in a table or index, page by page, then optionally drops rows with a FilterExpression. In AWS SDK v3 you send a ScanCommand and loop on LastEvaluatedKey until the whole table is read.

Code

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

Explanation

• FilterExpression — applied after the read, on the server. It shrinks the response but not the cost: you pay to read every item scanned, filtered or not.
• ExpressionAttributeNames — the filtered attribute is aliased (#filter0 → Year), which keeps reserved words like Year safe.
• Pagination — each Scan page reads at most 1 MB before filtering, so a filtered page can come back empty while still setting LastEvaluatedKey. You must keep looping until it's undefined, or you'll silently miss matches.
• Add Limit to cap items evaluated per page (pre-filter) — it limits how many items are read, not necessarily the number of matches returned.
• For a large full-table scan, split the work across workers with Segment / TotalSegments (a parallel scan).
• Prefer Query. Scan reads the whole table; on anything but a tiny table it's slow and expensive.

Do it visually

Assembling a filter by hand? The DynamoDB Expression Builder builds the FilterExpression + name/value maps and copies runnable code.

To explore tables in a GUI — with filtered, paginated result grids and copy-as-code — download DynoTable, instead of scanning blind from a script.

Related guides

• Query vs. Scan — when (rarely) a Scan is justified.
• Why is my DynamoDB Scan slow and expensive? — the cost model and how to avoid it.
• DynamoDB ProvisionedThroughputExceededException — what a full-table scan does to a provisioned table's capacity.
• DynamoDB ThrottlingException — the other throttle, and how exponential backoff handles it.

References

• Scan — Amazon DynamoDB API Reference
• ScanCommand — AWS SDK for JavaScript v3 Reference
• Scanning tables — Amazon DynamoDB Developer Guide
• Capacity unit consumption — Amazon DynamoDB Developer Guide

Last verified 2026-07-13 against the official AWS documentation linked above.