Intermediate6 min read

DynamoDB TTL: How Expiring Items Get Deleted

Time to Live (TTL) lets DynamoDB delete items automatically once a timestamp you store on them passes. You name one attribute holding a Unix-epoch expiry, and DynamoDB deletes expired items in the background, without a delete job of yours and without consuming write capacity.

Take an append-only audit log for a multi-tenant SaaS: one item per event under the tenant's partition key (PK = TENANT#acme). Each tenant has a retention policy: keep events for 90 days, 1 year, or 7 years for the compliance-heavy ones. TTL enforces that without a delete sweep of your own.

How does DynamoDB TTL work?

You enable TTL on the table and name one attribute; DynamoDB deletes each item some time after the timestamp in that attribute passes.

  • TTL is one attribute holding a Unix-epoch (seconds) timestamp. When that time passes, the item becomes eligible for deletion.
  • Deletion is background and best-effort: typically within a few days of expiry, not the exact second.
  • TTL deletes are free. They don't consume write capacity, though on a global table the replicated delete costs a write in every other replica Region.
  • Expired-but-not-yet-deleted items still appear in reads, so filter on the expiry attribute if you need to hide them immediately.

The problem: expiring old data yourself is expensive

Without TTL, enforcing "drop events older than 90 days" means running your own reaper: scan (or query) for old items on a schedule and DeleteItem each one. That scan burns read capacity, the deletes burn write capacity, and you own the schedule, the failures, and the retries.

For a high-volume audit log, that cost grows with every event you keep. TTL moves the job into DynamoDB, and the deletes are free.

How TTL works

You enable TTL on a table and tell it which attribute holds the expiry:

aws dynamodb update-time-to-live --table-name audit-log \
  --time-to-live-specification "Enabled=true, AttributeName=expiresAt"

The value must be a Number holding Unix epoch time in seconds. TTL ignores an item whose attribute isn't a Number, and one whose value is more than five years in the past (computing TTL).

DynamoDB "automatically deletes expired items within a few days of their expiration time, without consuming write throughput" (TTL docs). Until then an expired item is still readable, and still updatable: set its TTL attribute to a future time, or remove it, and it won't be deleted.

Put a condition such as attribute_exists(PK) on that update. Without one, an update that lands after TTL has deleted the item creates it again, with only the attributes the update sets.

A worked example: per-tenant retention

Each audit event carries an expiresAt attribute set when the event is written: now + the tenant's retention window, in epoch seconds.

PKSKactionexpiresAtnote
TENANT#acmeEVENT#2026-03-26T…#a0login.success178225920090-day tenant: eligible now
TENANT#acmeEVENT#2026-06-24T…#a1invoice.export1790035200still inside window
TENANT#globex EVENT#2026-06-24T…#b9role.granted20031840007-year compliance tenant

With TTL enabled on expiresAt, acme's 90-day event becomes eligible when the clock passes 1782259200, and DynamoDB deletes it on its own, typically within a few days.

The compliance tenant's events carry a far-future expiresAt, so they survive: same table, same mechanism, different retention per item.

The write side is just adding one number when you create the event. You can compose the SET expiresAt = :ttl clause and verify the typed :ttl value in the DynamoDB Expression Builder.

To hide an expired-but-undeleted event from a read immediately, add expiresAt > :now to the query's FilterExpression. A filter doesn't reduce read cost (query vs scan).

Every audit event carries expiresAt. On a table where some items have none, use attribute_not_exists(expiresAt) OR expiresAt > :now.

Archive expired items

To keep a copy of each event TTL deletes, read the deletes from a stream. Enable it with OLD_IMAGE (or NEW_AND_OLD_IMAGES) so the delete record carries the item, then attach a Lambda whose filter matches only TTL deletes (TTL and Streams):

aws lambda create-event-source-mapping --function-name archive-expired \
  --event-source-arn "$STREAM_ARN" --starting-position TRIM_HORIZON \
  --filter-criteria '{"Filters":[{"Pattern":"{\"userIdentity\":{\"type\":[\"Service\"],\"principalId\":[\"dynamodb.amazonaws.com\"]}}"}]}'

That filter is the one AWS's TTL and Streams page publishes, so keep it. But Lambda's DynamoDB filtering page says event source mappings "only support filtering on the dynamodb key".

The two pages disagree, so the filter can't be your only gate. The function must check the marker itself, null-safe: a user write or delete has no userIdentity.

export const handler = async (event) => {
  for (const record of event.Records) {
    const id = record.userIdentity;
    if (id?.type !== 'Service' || id?.principalId !== 'dynamodb.amazonaws.com') {
      continue; // a user write or delete: not a TTL expiry
    }
    await archive(record.dynamodb.OldImage); // your S3 PutObject or Firehose PutRecord
  }
};

You can't test this path on DynamoDB Local: its TTL delete records carry no userIdentity, so the check skips them.

The record arrives after the item is gone, and the stream keeps it for 24 hours. A consumer that is down longer loses those items; the Streams guide covers the failure settings and the longer-retention path. On a global table, only the Region that ran the delete marks the record.

Do it in DynoTable

The classic TTL bug is a wrong expiresAt: stored in milliseconds instead of seconds, or as an ISO string. Either way the item never expires. A millisecond value reads as a date about 56,000 years out, and TTL ignores a String.

DynoTable shows each item's attributes with their DynamoDB types, so you can confirm expiresAt is a Number in epoch seconds (not a String, not milliseconds) before you trust TTL with real retention.

Verifying the expiresAt attribute on an audit event in DynoTable is a Number in Unix-epoch seconds, the only value TTL acts on.
Verifying the expiresAt attribute on an audit event in DynoTable is a Number in Unix-epoch seconds, the only value TTL acts on.

Pitfalls and next steps

  • Epoch seconds, as a Number. A millisecond value pushes expiry ~56,000 years out; an ISO string is ignored entirely. Paste the value into the TTL converter: it detects seconds vs milliseconds and flags exactly this mistake.
  • Repair items already written wrong. Fixing the writer doesn't touch stored items. Scan with expiresAt > :ms (:ms = 100000000000, year 5138 as seconds) or attribute_type(expiresAt, :s) (:s = "S") to find them, then SET expiresAt to the right value in seconds on each.
  • Backfills can land too far back. A backfill that stamps old events with createdAt + retention can produce values more than five years in the past, which TTL ignores. Delete those events directly instead.
  • Don't rely on the deletion timing. A few days can pass between expiry and deletion. To hide expired items, filter on the attribute in reads. When a deletion must happen on time and be provable, delete the items yourself with DeleteItem (or BatchWriteItem) at the deadline, from a scheduled job that queries the expired range, and log it, with TTL as the backstop. Your stream handler skips these deletes as user writes, so if you also archive, the job writes each item it queried to the archive before deleting it. If TTL reaps an item between the job's read and its delete, both paths archive it, so key each archived object by the item's primary key (an S3 object per key overwrites the duplicate; a Firehose stream needs dedupe downstream).
  • TTL deletes still hit . Removing an item also removes it from any secondary index it was in. If a count must track live items, keep it from the stream (decrement on each REMOVE record, TTL deletes included) instead of counting the index.

TTL handles the end of an event's life cheaply. The next question is what you pay for the writes in the first place: On-Demand vs Provisioned capacity.

Download DynoTable to inspect your items' attribute types and confirm your TTL attribute is a Unix-epoch Number before you flip TTL on.

By Dmitriy · Updated