DynamoDB TTL: Epoch Converter, Setup and the Rules That Bite

DynamoDB Time to Live deletes an item for free once the time in its TTL attribute has passed. The attribute has to be a Number holding Unix epoch seconds, and most TTL problems are that value being something else: milliseconds, a string, a date in the past, or a date so far in the past that DynamoDB ignores it. The converter checks the value; the type is on you.

Convert a date to a TTL value, or check one

Paste epoch seconds, epoch milliseconds, or a date. You get the number to store, what it means in UTC and in your timezone, how far away it is, and a warning for each thing DynamoDB would reject or misread. The presets fill in a value relative to now.

What DynamoDB expects

The TTL attribute must be a Number holding Unix epoch time in seconds, such as 1758240000. Items whose TTL attribute is any other type, including a numeric string, are skipped by the TTL process and never deleted. A millisecond value is a Number too, so the TTL process accepts it, reads it as seconds, and schedules the item tens of thousands of years out. That item never expires either.

A TTL more than five years in the past is ignored. Anything between five years ago and now counts as already expired.

There is no minimum. Five minutes from now is a valid TTL.

Getting the current time in seconds is one line in most languages: Math.floor(Date.now() / 1000) in JavaScript, int(time.time()) in Python, System.currentTimeMillis() / 1000L in Java, date +%s in a shell. For the other timestamp formats a table tends to hold, see working with timestamps in DynamoDB.

Enabling TTL

TTL is a table setting: you name the attribute once, and every item that carries a Number in that attribute becomes eligible. The attribute name is case-sensitive and has to match what your code writes. Enabling takes about an hour to reach every partition.

With the CLI

aws dynamodb update-time-to-live \
  --table-name TTLExample \
  --time-to-live-specification "Enabled=true, AttributeName=ttl"

aws dynamodb describe-time-to-live --table-name TTLExample
aws dynamodb update-time-to-live \
  --table-name TTLExample \
  --time-to-live-specification "Enabled=true, AttributeName=ttl"

aws dynamodb describe-time-to-live --table-name TTLExample

With the CDK

import * as dynamodb from "aws-cdk-lib/aws-dynamodb"

const table = new dynamodb.Table(this, "TableWithTTL", {
  billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
  partitionKey: { name: "pk", type: dynamodb.AttributeType.STRING },
  timeToLiveAttribute: "ttl",
})
import * as dynamodb from "aws-cdk-lib/aws-dynamodb"

const table = new dynamodb.Table(this, "TableWithTTL", {
  billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
  partitionKey: { name: "pk", type: dynamodb.AttributeType.STRING },
  timeToLiveAttribute: "ttl",
})

With CloudFormation

TimeToLiveSpecification:
  AttributeName: ttl
  Enabled: true
TimeToLiveSpecification:
  AttributeName: ttl
  Enabled: true

In the console

Open the table, choose the Additional settings tab, and turn on Time to Live. The console lets you simulate an expiry date and lists a few items that would match, which is a quick way to confirm the attribute name and the value format before relying on it.

The rules that bite

Expired items are typically deleted within a few days, not immediately. Until then they still come back from a Query or a Scan, and they keep costing storage and read capacity until they go, so filter them out on read. Note that ttl is a reserved word, so it needs a placeholder:

import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb"

const client = DynamoDBDocumentClient.from(new DynamoDBClient({}))

await client.send(
  new QueryCommand({
    TableName: "sessions",
    KeyConditionExpression: "pk = :pk",
    FilterExpression: "#ttl > :now",
    ExpressionAttributeNames: { "#ttl": "ttl" },
    ExpressionAttributeValues: {
      ":pk": "user#123",
      ":now": Math.floor(Date.now() / 1000),
    },
  })
)
import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb"

const client = DynamoDBDocumentClient.from(new DynamoDBClient({}))

await client.send(
  new QueryCommand({
    TableName: "sessions",
    KeyConditionExpression: "pk = :pk",
    FilterExpression: "#ttl > :now",
    ExpressionAttributeNames: { "#ttl": "ttl" },
    ExpressionAttributeValues: {
      ":pk": "user#123",
      ":now": Math.floor(Date.now() / 1000),
    },
  })
)

Renaming the attribute means disabling TTL and enabling it again with the new name, and TTL keeps deleting for about half an hour after you disable it. UpdateTimeToLive is not idempotent: calling it while TTL is already on, or twice within an hour, returns a ValidationException, so treat "already enabled" as success in your code.

A table restored from a backup comes back with TTL off. Turn it on again.

Deletes made by TTL cost nothing and consume no write capacity. The exception is global tables, where the delete is replicated to the other regions and each replica charges a replicated write.

TTL deletes show up in DynamoDB Streams as service deletes, with userIdentity.type set to Service and principalId to dynamodb.amazonaws.com, which is how you archive expired items to S3 or trigger cleanup elsewhere. They are only marked that way in the Region where the delete happened, not in global table replicas. Expired items are also removed from every secondary index, as any delete is.

You can still update an item that has expired but not yet been deleted. Moving its TTL into the future, or removing the attribute, rescues it. Use a condition expression when you do, in case the delete has already happened.

When TTL is the right tool

Session records, one-time tokens, idempotency keys, rate-limit counters, shopping carts, and any event or log row with a retention period. In each case the item's useful life is known when it is written, so the TTL can be written with it and recomputed on every update. That keeps the table lean without a cleanup job and without paying write capacity to delete what you are no longer reading.