DynamoDB Pagination

Pagination splits a large result into smaller pages. DynamoDB returns at most 1 MB of data per Query or Scan call. A table with millions of items needs many calls, and a marker tells DynamoDB where the next call starts.

The Book Bookmark Picture

A reader never swallows a thousand-page book in one sitting. The reader reads a chunk, slips a bookmark between the pages, and returns to the bookmark later. DynamoDB pagination works the same way. Each response ends with a bookmark, and the next request starts exactly there.

How the Bookmark Works

When more data remains after the first page, the response includes a field named LastEvaluatedKey. The field holds the primary key of the last item DynamoDB examined. Pass that value as ExclusiveStartKey in the next request, and DynamoDB continues after that item.

Request 1:  Query PK = "CUSTOMER#C001"
Response 1: 40 items + LastEvaluatedKey = { PK: "CUSTOMER#C001", SK: "ORDER#0040" }

Request 2:  Query PK = "CUSTOMER#C001"
            ExclusiveStartKey = { PK: "CUSTOMER#C001", SK: "ORDER#0040" }
Response 2: 40 items + LastEvaluatedKey = { ... "ORDER#0080" }

Request 3:  ... continues
Response 3: 12 items + no LastEvaluatedKey  → finished ✓

A response without LastEvaluatedKey signals the end of the data. An empty marker is the only reliable stop signal. A page with fewer items than expected does not mean the data has ended.

A Simple Pagination Loop

all_items = []
start_key = null

REPEAT
    response = Query(table, key_condition, ExclusiveStartKey = start_key)
    add response.Items to all_items
    start_key = response.LastEvaluatedKey
UNTIL start_key is null

Most SDKs offer a paginator helper that runs this loop for you.

The Limit Parameter

The Limit parameter caps how many items DynamoDB evaluates in one call. Set Limit to 20, and DynamoDB reads at most 20 items before it stops and returns a bookmark. Applications use Limit to build screens that show 20 results at a time.

Pagination with Filter Expressions

A filter expression runs after DynamoDB reads the data. A page may contain fewer items than Limit, or even zero items, while a LastEvaluatedKey still exists.

Limit = 20, FilterExpression = Status = "SHIPPED"

DynamoDB reads 20 items → 3 have Status SHIPPED
Response: 3 items + LastEvaluatedKey (more data may exist)

Keep calling until LastEvaluatedKey disappears. A better design uses a sort key or index that places the wanted items together, so the filter becomes unnecessary.

Sort Order

Query returns items in ascending sort key order. Set ScanIndexForward to false to reverse the order. Descending order suits screens that show the newest entries first.

Pagination for Web and Mobile Screens

A browser or mobile app often needs a Next Page button. The server sends the LastEvaluatedKey to the client as a page token. The client sends the token back to request the next page.

• Encode the token as a single string, for example with Base64.
• Sign or encrypt the token when the key contains sensitive values.
• Validate the token on the server before use.
• Expect no direct jump to page 7. DynamoDB moves forward from a bookmark only.

Parallel Scan

A Scan over a huge table runs faster when several workers share the job. Set TotalSegments to the number of workers, and give each worker its own Segment number. Each worker paginates through its own slice.

TotalSegments = 4
Worker 0 → Segment 0
Worker 1 → Segment 1
Worker 2 → Segment 2
Worker 3 → Segment 3

Parallel scans consume capacity quickly, so run them with care on production tables.

Summary

• Query and Scan return at most 1 MB per call.
• LastEvaluatedKey works as a bookmark, and ExclusiveStartKey resumes from it.
• The absence of LastEvaluatedKey marks the final page.
• Limit caps evaluated items, and filters can shrink pages further.
• Applications send the bookmark to clients as a page token.