DynamoDB TTL: The Complete Guide to Expiring Items

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 reaps expired items in the background — no reaper job, no extra cost.

In the audit-log scenario each tenant has a retention policy: keep events for 90
days, or 1 year, or 7 for the compliance-heavy ones. TTL is how you enforce that
without running your own delete sweep.

How does DynamoDB TTL work?

DynamoDB TTL auto-deletes items once a Unix-epoch (seconds) timestamp you store in a
designated attribute passes. You enable TTL on the table, name the expiry attribute, and
DynamoDB reaps expired items in the background — typically within a few days, with no
write-capacity cost. Expired items stay readable until they're physically deleted.

• 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's a constant, growing tax just to throw data
away. TTL moves the entire job into DynamoDB, for free.

How TTL works

You enable TTL on a table and tell it which attribute holds the expiry. Per
the
AWS announcement,
you designate an item attribute holding a Unix-epoch expiration timestamp, and
DynamoDB handles deletion automatically in the background without affecting table
performance.

Two properties matter for correctness:

• It's best-effort, not exact. DynamoDB scans for expired items and deletes them in the background; deletion typically happens within a few days of expiry. An item is eligible at its timestamp but may linger briefly.
• Expired items are still readable until reaped. A Query can return an item whose TTL has passed but which hasn't been deleted yet — so add a FilterExpression on the expiry attribute if "expired = invisible immediately" is a hard requirement.

And TTL deletes do not consume write capacity, which is what makes it strictly
cheaper than a self-run reaper.

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:

TTL is enabled with expiresAt as the TTL attribute. When acme's 90-day event
crosses 1782259200, DynamoDB deletes it on its own within roughly two 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-unreaped event from a read immediately, add
expiresAt > :now to the query's FilterExpression — though remember a filter
doesn't reduce read cost (query vs scan).

Do it in DynoTable

The classic TTL bug is a wrong expiresAt: stored in milliseconds instead of
seconds, or as an ISO string, so the item either never expires or vanishes
immediately. The only way to catch it is to look at the actual stored value and
its type.

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.

Pitfalls and next steps

• Epoch seconds, as a Number. This is the single most common TTL mistake. A millisecond value pushes expiry ~50,000 years out; an ISO string is ignored entirely. Verify the type and unit. Paste the value into the TTL converter — it auto-detects seconds vs milliseconds and flags exactly this mistake.
• Don't rely on the deletion timing. A few days can pass between expiry and deletion. If "gone the instant it expires" matters, filter on the attribute in reads; don't assume the row is physically gone.
• TTL deletes appear in Streams. A TTL deletion emits a stream record flagged as system-generated — the standard hook for archiving expiring events to S3 before they disappear. See DynamoDB Streams.
• TTL deletes still hit GSIs. Removing an item also removes it from any secondary index it was in — which is the intended cleanup, but worth knowing if an index drove a count.

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.