How Does the DynamoDB TTL Feature Automatically Expire and Delete Outdated Items?

Amazon DynamoDB Time to Live (TTL) is an automated, zero-cost data lifecycle management feature that identifies and purges expired items from your tables without consuming provisioned read or write throughput. It works by monitoring a user-defined attribute on each item that contains a timestamp. A dedicated background process continually evaluates these timestamps against the current time, marking and deleting items that have passed their expiration date.

Defining the Expire Attribute

To use TTL, you must designate a specific attribute name on your table to store the expiration timestamp. This attribute must meet strict criteria:

  • Data Type: The attribute must be stored as a Number data type. String or binary attributes are ignored by the TTL mechanism.
  • Format: The timestamp must be formatted in Unix epoch time in seconds (for example, 1700000000). Storing timestamps in milliseconds will prevent the item from expiring as intended.
  • Range Validation: DynamoDB ignores TTL attributes with timestamps that are more than five years in the past to prevent accidental mass deletions due to data entry errors.

If an item lacks the designated TTL attribute, DynamoDB simply retains the item indefinitely until it is manually updated or deleted.

The Automatic Deletion Mechanism

The TTL operation runs asynchronously in the background and is completely decoupled from your application's normal traffic. It follows a two-step lifecycle:

Expiration vs. Deletion

An item reaches its expiration point as soon as the current Unix system time exceeds the timestamp value stored in its TTL attribute. However, expiration does not instantly remove the item from the database.

DynamoDB uses an internal scanner to sweep table partitions and remove items marked for expiration. Physical deletion typically occurs within 48 hours of expiration, depending on table size and overall system workload.

System Impact and Throughput

Because the deletion process runs as a system background task:

  • It does not consume Read Capacity Units (RCUs) or Write Capacity Units (WCUs) from your table provisioned limits.
  • It does not impact read/write request latency or throughput available to your workload.
  • Deletions automatically clear up storage space, reducing overall table storage costs.

Handling Pending Deletions in Your Application

Because there can be a delay between when an item expires and when the background scanner physically removes it, expired items can still appear in GetItem, Query, or Scan requests.

To ensure strict application correctness, you should include logic in your application layer:

  1. Client-Side Filtering: Check the TTL timestamp in your application code after retrieving an item to ensure it is still valid before processing.
  2. Filter Expressions: Use a FilterExpression in your Query or Scan operations to exclude items where the TTL attribute is less than or equal to the current Unix time.

Tracking TTL Deletions via DynamoDB Streams

When TTL background workers delete an item, DynamoDB logs the operation to DynamoDB Streams if the stream feature is enabled on the table.

The resulting stream record contains a userIdentity field identifying the deletion as a system action rather than a user API call:

  • userIdentity.type: "Service"
  • userIdentity.principalId: "dynamodb.amazonaws.com"

This stream integration makes TTL useful for archiving expired data—such as sending deleted session records or logs directly to AWS Lambda or Amazon S3 before permanent removal.