Unprocessed items handling in DynamoDB

Introduction

Sometimes when you send many items to DynamoDB at once, some items might not be saved immediately. Handling unprocessed items helps you try saving them again.

When you use batch write operations to add or delete many items at once.

When you want to make sure all your data is saved even if DynamoDB is busy.

When you want to retry saving items that DynamoDB could not process the first time.

When you want to avoid losing data during bulk operations.

When you want to handle limits DynamoDB sets on how many items can be processed at once.

Syntax

DynamoDB

BatchWriteItemRequest {
  RequestItems: {
    TableName: [
      { PutRequest: { Item: {...} } },
      { DeleteRequest: { Key: {...} } }
    ]
  }
}

Response {
  UnprocessedItems: {
    TableName: [
      { PutRequest: { Item: {...} } },
      { DeleteRequest: { Key: {...} } }
    ]
  }
}

UnprocessedItems in the response contains items DynamoDB did not save.

You should resend UnprocessedItems to DynamoDB to complete the operation.

Examples

Send two requests: add a book and delete another book in one batch.

DynamoDB

BatchWriteItemRequest {
  RequestItems: {
    'Books': [
      { PutRequest: { Item: { 'ISBN': { S: '123' }, 'Title': { S: 'Learn SQL' } } } },
      { DeleteRequest: { Key: { 'ISBN': { S: '456' } } } }
    ]
  }
}

DynamoDB did not process the add book request. You need to retry it.

DynamoDB

Response {
  UnprocessedItems: {
    'Books': [
      { PutRequest: { Item: { 'ISBN': { S: '123' }, 'Title': { S: 'Learn SQL' } } } }
    ]
  }
}

Sample Program

This example shows how to send a batch write request using AWS CLI, check for unprocessed items, and resend them to ensure all items are saved.

DynamoDB

aws dynamodb batch-write-item --request-items file://batch.json > response.json

# Check response.json for UnprocessedItems
# If UnprocessedItems exist, extract them to unprocessed.json (e.g., using jq '{RequestItems: .UnprocessedItems}' response.json > unprocessed.json)
# Then resend:
aws dynamodb batch-write-item --request-items file://unprocessed.json

Important Notes

Always check the UnprocessedItems in the response after a batch write.

Retry sending unprocessed items until none remain to ensure data consistency.

Batch operations have size limits; splitting large batches can reduce unprocessed items.

Summary

Unprocessed items happen when DynamoDB can't save all items in a batch at once.

You should always check and resend unprocessed items to avoid data loss.

Handling unprocessed items helps keep your data safe and complete.