Fetch All Pokémon

What you'll learn

Scan reads all items from a table without needing to know specific keys.
Each request reads up to 1 MB; continue while LastEvaluatedKey is present.
FilterExpression is applied after reading and does not reduce consumed read capacity.

Section 01

What is a Scan Operation?

Think of your DynamoDB table like a huge toy box full of Pokémon cards. A Scan is like dumping out the entire toy box and looking through every single card one by one to see what you have.

You don't need to know the name of a specific Pokémon beforehand—you just want to see everything that's in there! DynamoDB will show you all the cards (items), but it might give them to you in small groups (pages) if there are too many to look at all at once.

Section 02

How Scan Works

When you perform a Scan operation:

DynamoDB reads every item in the table.
A request reads up to 1 MB (or its Limit) before filtering. You pay for every item read, not just the ones returned: 4 KB read units, at half price with the default eventually consistent reads.
You can add filters to only show certain Pokémon, but DynamoDB still looks at everything first.
To get the next page, you use the LastEvaluatedKey from the previous response.

Ready · 8 steps · Sprig

This animation plays when you scroll to it. Press Play to start it now.

All steps as text

Your app sends Scan to the Pokemon table.
P0 returns Bulbasaur, Charmander, Mew.
P1 returns Jigglypuff, Psyduck.
P2 returns Squirtle, Meowth.
P3 returns Pikachu.
This call consumed 1 RCU.
The page holds 8 items. No LastEvaluatedKey, so this was the last page.
DynamoDB responds with success: 8 items, every partition read.

Section 03

Scan Operation Example

Here's the AWS SDK v3 request shape. ServerlessCreed parses this code and runs it against deterministic fixtures; it never connects to AWS.

One request returns only one page. To fetch all items, repeat the scan with ExclusiveStartKey until the response has no LastEvaluatedKey. The @aws-sdk/lib-dynamodb package automatically converts DynamoDB's native format to JavaScript objects, making your code much cleaner!

Scan command with AWS SDK v3TypeScript

// Import the DynamoDBClient class - this is the main client used to interact with DynamoDB
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
// Import the document client wrapper and its ScanCommand (plain JS objects in and out)
import { DynamoDBDocumentClient, ScanCommand } from "@aws-sdk/lib-dynamodb";

// Request-shape example only: ServerlessCreed never executes this client.
const client = new DynamoDBClient({
  // Specify the AWS region where your DynamoDB table is located (ap-south-1 = Asia Pacific Mumbai)
  region: "ap-south-1",
});
const docClient = DynamoDBDocumentClient.from(client);

// Define an async function to perform the scan operation
async function scanTable() {
  // Create a new ScanCommand with the table name you want to scan
  const command = new ScanCommand({
    // Specify the name of the DynamoDB table to scan
    TableName: "Pokemon",
  });

  // Use try-catch to handle potential errors during the scan operation
  try {
    // Send the scan command to DynamoDB and wait for the response
    const response = await docClient.send(command);
    // Log the items returned from the scan operation
    console.log("Scan succeeded:", response.Items);
  } catch (err) {
    // If an error occurs, log the error message
    console.error("Scan failed:", err);
  }
}

Fetch every page (manual loop)TypeScript

async function scanAllPokemon() {
  const allPokemon = [];
  let ExclusiveStartKey; // undefined on the first request

  do {
    const page = await docClient.send(
      new ScanCommand({ TableName: "Pokemon", ExclusiveStartKey })
    );
    allPokemon.push(...(page.Items ?? []));
    ExclusiveStartKey = page.LastEvaluatedKey; // undefined on the last page
  } while (ExclusiveStartKey);

  return allPokemon;
}
// Shortcut: paginateScan from @aws-sdk/lib-dynamodb runs this loop for you.

Practice

Your turn

The example scans a Users table. Change TableName to "Pokemon" so it scans our Pokémon table, then press Run code. Stuck? The Reference solution tab has the answer.

Only the TableName line is editable. Point it at "Pokemon".

// @ts-nocheck
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, ScanCommand } from "@aws-sdk/lib-dynamodb";
// This authentic SDK-shaped code is parsed by ServerlessCreed's local emulator.
// It is never executed against AWS and never receives credentials.
const client = new DynamoDBClient({
  region: "ap-south-1",
});
const docClient = DynamoDBDocumentClient.from(client);
async function scanTable() {
  // TODO: Your task is to modify the TableName below
  // The current code scans a "Users" table, but you need to scan the "Pokemon" table instead
  // Replace "Users" with "Pokemon" to complete the challenge
  const command = new ScanCommand({
    TableName: "Users", // ⬅️ Change this value to "Pokemon"
  });
  // The emulator validates the request shape and returns deterministic fixtures.
  // No changes needed in the try-catch block
  try {
    const response = await docClient.send(command);
    console.log("Scan succeeded:", response.Items);
  } catch (err) {
    console.error("Scan failed:", err);
  }
}

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

// This authentic SDK-shaped code is parsed by ServerlessCreed's local emulator.
// It is never executed against AWS and never receives credentials.
const client = new DynamoDBClient({
  region: "ap-south-1",
});
const docClient = DynamoDBDocumentClient.from(client);

async function scanTable() {
  // TODO: Your task is to modify the TableName below
  // The current code scans a "Users" table, but you need to scan the "Pokemon" table instead
  // Replace "Users" with "Pokemon" to complete the challenge
  const command = new ScanCommand({
    TableName: "Users", // ⬅️ Change this value to "Pokemon"
  });

  // The emulator validates the request shape and returns deterministic fixtures.
  // No changes needed in the try-catch block
  try {
    const response = await docClient.send(command);
    console.log("Scan succeeded:", response.Items);
  } catch (err) {
    console.error("Scan failed:", err);
  }
}

Ctrl/⌘ Enter to run · simulated, no AWS callsSimulated — no AWS calls

Check

Check your understanding

Quick Quiz · one question, as many tries as you need.

What does the Scan operation do in DynamoDB?

Choose one answer.