How to Scan a DynamoDB Table: Syntax and Example

To scan a DynamoDB table, use the Scan operation which reads every item in the table. You can specify filters to narrow results, but scanning reads all data and can be slow for large tables. Use Scan with pagination to handle large datasets efficiently.

Syntax

The Scan operation reads all items in a DynamoDB table. You can optionally add a FilterExpression to return only items that match certain conditions. Use ExclusiveStartKey and LastEvaluatedKey for pagination to scan large tables in parts.

• TableName: The name of the table to scan.
• FilterExpression: Optional condition to filter results.
• ExpressionAttributeValues: Values used in the filter expression.
• ExclusiveStartKey: Key to start scanning from (for pagination).

javascript

Scan({
  TableName: 'YourTableName',
  FilterExpression: 'attribute_exists(AttributeName)',
  ExpressionAttributeValues: { ':val': { S: 'Value' } },
  ExclusiveStartKey: { PrimaryKey: { S: 'LastKeyValue' } }
})

Example

This example shows how to scan a DynamoDB table named Products to get all items. It uses AWS SDK for JavaScript v3 and handles pagination to retrieve all results.

javascript

import { DynamoDBClient, ScanCommand } from "@aws-sdk/client-dynamodb";

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

async function scanTable() {
  let items = [];
  let ExclusiveStartKey = undefined;

  do {
    const params = {
      TableName: "Products",
      ExclusiveStartKey,
    };

    const command = new ScanCommand(params);
    const data = await client.send(command);

    if (data.Items) {
      items = items.concat(data.Items);
    }

    ExclusiveStartKey = data.LastEvaluatedKey;
  } while (ExclusiveStartKey);

  return items;
}

scanTable().then(items => {
  console.log("Scanned items:", items);
}).catch(console.error);

Output

Scanned items: [ { /* item 1 attributes */ }, { /* item 2 attributes */ }, ... ]

Common Pitfalls

• Reading large tables without pagination: Scanning large tables without handling LastEvaluatedKey can cause incomplete results.
• Using Scan instead of Query: Scan reads the whole table and is slower; use Query when you can filter by primary key.
• Ignoring provisioned throughput: Scan consumes a lot of read capacity units; it can throttle your table.

javascript

/* Wrong: No pagination, may miss data */
const params = { TableName: "Products" };
const data = await client.send(new ScanCommand(params));
console.log(data.Items);

/* Right: Use pagination to get all items */
let items = [];
let ExclusiveStartKey;
do {
  const params = { TableName: "Products", ExclusiveStartKey };
  const data = await client.send(new ScanCommand(params));
  items = items.concat(data.Items);
  ExclusiveStartKey = data.LastEvaluatedKey;
} while (ExclusiveStartKey);
console.log(items);

Quick Reference

Parameter	Description
TableName	Name of the DynamoDB table to scan
FilterExpression	Optional condition to filter scanned items
ExpressionAttributeValues	Values used in filter expressions
ExclusiveStartKey	Key to start scan from for pagination
LastEvaluatedKey	Key returned to continue scanning next page

Key Takeaways

Use the Scan operation to read all items in a DynamoDB table but prefer Query when possible for efficiency.

Always handle pagination with LastEvaluatedKey to retrieve all results from large tables.

Scan can consume a lot of read capacity units and may slow down your table if overused.

Use FilterExpression to narrow down results but remember Scan still reads all data internally.

Test your scan queries on small datasets before running on large tables to avoid performance issues.