Stream record types (NEW_IMAGE, OLD_IMAGE) in DynamoDB

Introduction

Stream record types help you see what changed in your database. They show the data before and after an update.

You want to track changes to items in your DynamoDB table.

You need to react when a new item is added or an existing item is updated.

You want to keep a backup of old data before it changes.

You want to audit who changed what and when in your database.

Syntax

DynamoDB

StreamRecord {
  Keys: { ... },
  NewImage: { ... },
  OldImage: { ... },
  StreamViewType: 'NEW_IMAGE' | 'OLD_IMAGE' | 'NEW_AND_OLD_IMAGES' | 'KEYS_ONLY'
}

NewImage shows the item after the change.

OldImage shows the item before the change.

Examples

This stream record shows the new version of the item after an insert or update.

DynamoDB

StreamViewType: 'NEW_IMAGE'
NewImage: { "id": "123", "name": "Alice" }

This stream record shows the old version of the item before it was changed or deleted.

DynamoDB

StreamViewType: 'OLD_IMAGE'
OldImage: { "id": "123", "name": "Bob" }

This stream record shows both old and new versions, useful for comparing changes.

DynamoDB

StreamViewType: 'NEW_AND_OLD_IMAGES'
NewImage: { "id": "123", "name": "Alice" }
OldImage: { "id": "123", "name": "Bob" }

Sample Program

This example shows a stream record where the item with id 123 changed its name from Bob to Alice.

DynamoDB

-- Assume DynamoDB stream is enabled with NEW_AND_OLD_IMAGES
-- Sample stream record for an update
{
  "Keys": { "id": { "S": "123" } },
  "NewImage": { "id": { "S": "123" }, "name": { "S": "Alice" } },
  "OldImage": { "id": { "S": "123" }, "name": { "S": "Bob" } },
  "StreamViewType": "NEW_AND_OLD_IMAGES"
}

Important Notes

Stream records only appear if you enable DynamoDB Streams on your table.

Choose the StreamViewType based on what data you want to capture: keys only, new image, old image, or both.

Summary

Stream record types show data before and/or after changes.

NEW_IMAGE shows the updated data.

OLD_IMAGE shows the data before the change.