How to Use ExclusiveStartKey for Pagination in DynamoDB

Use ExclusiveStartKey in DynamoDB queries or scans to start fetching results from a specific point, enabling pagination. Pass the last evaluated key from the previous response as ExclusiveStartKey in the next request to continue retrieving the next page of results.

Syntax

The ExclusiveStartKey is an optional parameter in DynamoDB Query or Scan operations. It tells DynamoDB where to start the next page of results.

It should be set to the LastEvaluatedKey value returned by the previous query or scan response.

• ExclusiveStartKey: A map of attribute names and values that defines the starting point for the next page.
• LastEvaluatedKey: The key returned by DynamoDB indicating there are more results to fetch.

javascript

const QueryInput = {
  TableName: 'YourTableName',
  KeyConditionExpression: 'PartitionKey = :pk',
  ExpressionAttributeValues: {
    ':pk': { S: 'PartitionKeyValue' }
  },
  ExclusiveStartKey: {  // Optional
    PartitionKey: { S: 'LastPartitionKeyValue' },
    SortKey: { N: 'LastSortKeyValue' }
  },
  Limit: 10
};

Example

This example shows how to paginate through a DynamoDB table using ExclusiveStartKey in Node.js with AWS SDK v3.

It fetches 2 pages of results, each with a limit of 2 items.

javascript

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

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

async function paginateQuery() {
  let ExclusiveStartKey = undefined;
  for (let page = 1; page <= 2; page++) {
    const params = {
      TableName: "Music",
      KeyConditionExpression: "Artist = :artist",
      ExpressionAttributeValues: {
        ":artist": { S: "No One You Know" }
      },
      Limit: 2,
      ExclusiveStartKey
    };

    const command = new QueryCommand(params);
    const response = await client.send(command);

    console.log(`Page ${page} results:`);
    console.log(response.Items);

    ExclusiveStartKey = response.LastEvaluatedKey;
    if (!ExclusiveStartKey) {
      console.log("No more pages.");
      break;
    }
  }
}

paginateQuery();

Output

[
  { Artist: { S: 'No One You Know' }, SongTitle: { S: 'Call Me Today' } },
  { Artist: { S: 'No One You Know' }, SongTitle: { S: 'Somewhere Down The Road' } }
]
Page 2 results:
[
  { Artist: { S: 'No One You Know' }, SongTitle: { S: 'I'm Your Puppet' } },
  { Artist: { S: 'No One You Know' }, SongTitle: { S: 'Lalala' } }
]
No more pages.

Common Pitfalls

• Not checking for LastEvaluatedKey: If you ignore this key, you won't know if more pages exist.
• Passing incorrect ExclusiveStartKey: The key must exactly match the primary key structure of your table.
• Using ExclusiveStartKey without Limit: Pagination is most useful with a limit to control page size.
• Assuming ExclusiveStartKey works with filters: Filters are applied after fetching, so pagination is based on keys, not filtered results.

javascript

/* Wrong: Not using LastEvaluatedKey for next page */
const paramsWrong = {
  TableName: "Music",
  KeyConditionExpression: "Artist = :artist",
  ExpressionAttributeValues: { ":artist": { S: "No One You Know" } },
  Limit: 2
};

/* Right: Using LastEvaluatedKey as ExclusiveStartKey */
const paramsRight = {
  ...paramsWrong,
  ExclusiveStartKey: lastEvaluatedKeyFromPreviousResponse
};

Quick Reference

• ExclusiveStartKey: Use to start next page from last key.
• LastEvaluatedKey: Returned by DynamoDB if more pages exist.
• Limit: Controls number of items per page.
• Pagination loop: Repeat query with ExclusiveStartKey until LastEvaluatedKey is null.

Key Takeaways

Use ExclusiveStartKey with the LastEvaluatedKey from the previous response to paginate.

Always check if LastEvaluatedKey exists to know if more pages are available.

Set a Limit to control how many items you get per page.

ExclusiveStartKey must match your table's primary key structure exactly.

Pagination works on keys, not on filtered results.