Computing time to live (TTL) - Amazon DynamoDB
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Computing time to live (TTL)

A common way to implement TTL is to set an expiration time for items based on when they were created or last updated. This can be done by adding time to the createdAt and updatedAt timestamps. For example, the TTL for newly created items can be set to createdAt + 90 days. When the item is updated the TTL can be recalculated to updatedAt + 90 days.

The computed expiration time must be in epoch format, in seconds. To be considered for expiry and deletion, the TTL can't be more than five years in the past. If you use any other format, the TTL processes ignore the item. If you set the expiration date to sometime in the future when you want the item to expire, the item will be expired after that time. For example, say that you set the expiration date to 1724241326 (which is Monday, August 21st, 2024 11:55:26 (GMT)). The item will be expired after the specified time.

Create an item and set the Time to Live

The following example demonstrates how to calculate the expiration time when creating a new item, using 'expireAt' as the TTL attribute name for JavaScript and 'expirationDate' for Python. An assignment statement obtains the current time as a variable. In the example, the expiration time is calculated as 90 days from the current time. The time is then converted to epoch format and saved as an integer data type in the TTL attribute.

Python
import boto3 from datetime import datetime, timedelta def create_dynamodb_item(table_name, region, primary_key, sort_key): """ Creates a DynamoDB item with an attached expiry attribute. :param table_name: Table name for the boto3 resource to target when creating an item :param region: string representing the AWS region. Example: `us-east-1` :param primary_key: one attribute known as the partition key. :param sort_key: Also known as a range attribute. :return: Void (nothing) """ try: dynamodb = boto3.resource('dynamodb', region_name=region) table = dynamodb.Table(table_name) # Get the current time in epoch second format current_time = int(datetime.now().timestamp()) # Calculate the expiration time (90 days from now) in epoch second format expiration_time = int((datetime.now() + timedelta(days=90)).timestamp()) item = { 'primaryKey': primary_key, 'sortKey': sort_key, 'creationDate': current_time, 'expirationDate': expiration_time } table.put_item(Item=item) print("Item created successfully.") except Exception as e: print(f"Error creating item: {e}") raise # Use your own values create_dynamodb_item('your-table-name', 'us-west-2', 'your-partition-key-value', 'your-sort-key-value')
JavaScript

In this request we add logic to compute the expiration time of the newly created item:

import { DynamoDBClient, PutItemCommand } from "@aws-sdk/client-dynamodb"; function createDynamoDBItem(table_name, region, partition_key, sort_key) { const client = new DynamoDBClient({ region: region, endpoint: `https://dynamodb.${region}.amazonaws.com` }); // Get the current time in epoch second format const current_time = Math.floor(new Date().getTime() / 1000); // Calculate the expireAt time (90 days from now) in epoch second format const expire_at = Math.floor((new Date().getTime() + 90 * 24 * 60 * 60 * 1000) / 1000); // Create DynamoDB item const item = { 'partitionKey': {'S': partition_key}, 'sortKey': {'S': sort_key}, 'createdAt': {'N': current_time.toString()}, 'expireAt': {'N': expire_at.toString()} }; const putItemCommand = new PutItemCommand({ TableName: table_name, Item: item, ProvisionedThroughput: { ReadCapacityUnits: 1, WriteCapacityUnits: 1, }, }); client.send(putItemCommand, function(err, data) { if (err) { console.log("Exception encountered when creating item %s, here's what happened: ", data, ex); throw err; } else { console.log("Item created successfully: %s.", data); return data; } }); } // use your own values createDynamoDBItem('your-table-name', 'us-east-1', 'your-partition-key-value', 'your-sort-key-value');

Update an item and refresh the Time to Live

This example is a continuation of the one from the previous section. The expiration time can be recomputed if the item is updated. The following example recomputes the expireAt timestamp to be 90 days from the current time.

Python
import boto3 from datetime import datetime, timedelta def update_dynamodb_item(table_name, region, primary_key, sort_key): """ Update an existing DynamoDB item with a TTL. :param table_name: Name of the DynamoDB table :param region: AWS Region of the table - example `us-east-1` :param primary_key: one attribute known as the partition key. :param sort_key: Also known as a range attribute. :return: Void (nothing) """ try: # Create the DynamoDB resource. dynamodb = boto3.resource('dynamodb', region_name=region) table = dynamodb.Table(table_name) # Get the current time in epoch second format current_time = int(datetime.now().timestamp()) # Calculate the expireAt time (90 days from now) in epoch second format expire_at = int((datetime.now() + timedelta(days=90)).timestamp()) table.update_item( Key={ 'partitionKey': primary_key, 'sortKey': sort_key }, UpdateExpression="set updatedAt=:c, expireAt=:e", ExpressionAttributeValues={ ':c': current_time, ':e': expire_at }, ) print("Item updated successfully.") except Exception as e: print(f"Error updating item: {e}") # Replace with your own values update_dynamodb_item('your-table-name', 'us-west-2', 'your-partition-key-value', 'your-sort-key-value')

The output from the update operation shows that, while the createdAt time is unchanged, the updatedAt and expireAt times have been updated. The expireAt time is now set to 90 days from the time of the last update, which is Thursday, October 19, 2023 at 1:27:15 PM.

partition_key createdAt updatedAt expireAt attribute_1 attribute_2

some_value

2023-07-17 14:11:05.322323 2023-07-19 13:27:15.213423 1697722035 new_value some_value
JavaScript
import { DynamoDBClient, UpdateItemCommand } from "@aws-sdk/client-dynamodb"; import { marshall, unmarshall } from "@aws-sdk/util-dynamodb"; async function updateDynamoDBItem(tableName, region, partitionKey, sortKey) { const client = new DynamoDBClient({ region: region, endpoint: `https://dynamodb.${region}.amazonaws.com` }); const currentTime = Math.floor(Date.now() / 1000); const expireAt = Math.floor((Date.now() + 90 * 24 * 60 * 60 * 1000) / 1000); ////is there a better way to do this? const params = { TableName: tableName, Key: marshall({ partitionKey: partitionKey, sortKey: sortKey }), UpdateExpression: "SET updatedAt = :c, expireAt = :e", ExpressionAttributeValues: marshall({ ":c": currentTime, ":e": expireAt }), }; try { const data = await client.send(new UpdateItemCommand(params)); const responseData = unmarshall(data.Attributes); console.log("Item updated successfully: %s", responseData); return responseData; } catch (err) { console.error("Error updating item:", err); throw err; } } //enter your values here updateDynamoDBItem('your-table-name', 'us-east-1', 'your-partition-key-value', 'your-sort-key-value');

The TTL examples discussed in this introduction demonstrate a method to ensure only recently updated items are kept in a table. Updated items have their lifespan extended, whereas items not updated post-creation expire and are deleted at no cost, reducing storage and maintaining clean tables.