Amazon DynamoDB
Developer Guide (API Version 2012-08-10)

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

Time to Live: How It Works

When Time to Live (TTL) is enabled on a table in Amazon DynamoDB, a background job checks the TTL attribute of items to determine whether they are expired.

TTL compares the current time in epoch time format to the time stored in the Time to Live attribute of an item. If the epoch time value stored in the attribute is less than the current time, the item is marked as expired and then deleted. This processing takes place automatically in the background and does not affect read or write traffic to the table.


The epoch time format is the number of seconds elapsed since 12:00:00 AM January 1, 1970 UTC.


DynamoDB typically deletes expired items within 48 hours of expiration. The exact duration within which an item truly gets deleted after expiration is specific to the nature of the workload and the size of the table. Items that have expired and have not been deleted still appear in reads, queries, and scans. These items can still be updated, and successful updates to change or remove the expiration attribute are honored.

As items are deleted, they are removed from any local secondary index and global secondary index immediately in the same eventually consistent way as a standard delete operation.

For example, consider a table named SessionData that tracks the session history of users. Each item in SessionData is identified by a partition key (UserName) and a sort key (SessionId). Additional attributes like UserName, SessionId, CreationTime, and ExpirationTime track the session information. The ExpirationTime attribute is set as the TTL attribute (not all of the attributes are shown).


UserName SessionId CreationTime ExpirationTime (TTL) SessionInfo
user1 74686572652773 1461931200 1461938400 {JSON Document} ...
user2 6e6f7468696e67 1461920400 1461927600 {JSON Document} ...
user3 746f2073656520 1461922200 1461929400 {JSON Document} ...
user4 68657265212121 1461925380 1461932580 {JSON Document}
user5 6e6572642e2e2e 1461920400 1461927600 {JSON Document} ...
... ... ... ... ...

In this example, each item has an ExpirationTime attribute value set when it is created. Consider the following record.


UserName SessionId CreationTime ExpirationTime (TTL) SessionInfo
user1 74686572652773 1461931200 1461938400 {JSON Document} ...

In this example, the item CreationTime is set to Friday, April 29 12:00 PM UTC 2016, and the ExpirationTime is set 2 hours later at Friday, April 29 2:00 PM UTC 2016. The item expires when the current time, in epoch format, is greater than the time in the ExpirationTime attribute. In this case, the item with the key { Username: user1, SessionId: 74686572652773 } expires after 2:00 PM (1461938400).


Due to the potential delay between expiration and deletion time, you might get expired items when you query for items. If you don’t want to view expired items when you issue a read request, you should filter them out. To do this, use a filter expression that returns only items where the Time to Live expiration value is greater than the current time in epoch format. For more information, see Filter Expressions for Query and Filter Expressions for Scan.