How to Paginate Query & Scan Results with the DynamoDB PHP Client

This bit of AWS Docs has all the info you could possible need on DynamoDB pagination, but it’s wordy. So here’s a quick summary and code sample for PHP.

  • DynamoDB respects a Limit argument in both Scan and Query, but it will also stop if the retrieved items exceed one megabyte regarldess of Limit.
  • If there are more items a LastEvaluatedKey will be returned in the response.
  • Pass that LastEvaluatedKey to ExclusiveStartKey in the next request.
use Aws\DynamoDb\DynamoDbClient;

function queryAll(DynamoDbClient $dynamo, array $request)
{
    $allItems = [];
    $lastEvaluatedKey = null;
    do {
        // copy so we don't mess with the original request
        $currentRequest = $request;
        $currentRequest['Limit'] = 10; // optional
        if ($lastEvaluatedKey) {
            $currentRequest['ExclusiveStartKey'] = $lastEvaluatedKey;
        }
        

        $response = $dynamo->query($currentRequest);

        // collect the returned items
        $allItems = array_merge($allItems, $response['Items'] ?? []);

        // grab the last evaluated key, and keep querying if it's present
        $lastEvaluatedKey = $response['LastEvaluatedKey'] ?? null;
    } while ($lastEvaluatedKey);
}

queryAll(new DynamoDbClient([
    'version' => 'latest',
    'region' => 'us-east-1',
]), [
    'TableName' => 'YourTable',
    'IndexName' => 'SomeSecondaryIndex',
    'KeyConditionExpression' => 'YourKey = :whatever',
    'ExpressionAttributeValues' => [
        ':whatever' => [
            'S' => 'abc123',
        ],
    ]
]);
  

This is really close to the seek method in SQL.