Burn Heal (Time to Live)

What you'll learn

TTL marks items for asynchronous background deletion; expiration is not immediate.
The TTL attribute must be a Number type representing Epoch Seconds.
Expired items can remain visible for days, so application reads should filter them out.

Section 01

Burn Heal (TTL)

Add an ExpirationTime attribute and enable that exact attribute as the table's TTL setting. Once the timestamp passes, the item becomes eligible for background deletion. Until DynamoDB removes it, your application must treat it as expired, for example by adding FilterExpression: "ExpirationTime > :now" to reads.

Writing an item with TTLJavaScript

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

const client = new DynamoDBClient({ region: "ap-south-1" });
const docClient = DynamoDBDocumentClient.from(client);

await docClient.send(new PutCommand({
  TableName: "StatusEffects",
  Item: {
    PokemonId: "Pikachu",
    Effect: "Burn",
    // Eligible for background deletion after 5 minutes; not an exact timer.
    ExpirationTime: Math.floor(Date.now() / 1000) + 300 
  }
}));

Ready · 5 steps · Amp

This animation plays when you scroll to it. Press Play to start it now.

All steps as text

Pikachu · Burn's ExpirationTime (now + 300 s) has passed, but TTL deletes asynchronously, so reads can still return it until the sweeper runs.
Your app sends GetItem to the StatusEffects table with PokemonId = "Pikachu", Effect = "Burn". Six minutes later, reading without checking ExpirationTime.
DynamoDB hashes "Pikachu" to a6bb8b2f, which routes the request to partition P3.
P3 returns Pikachu · Burn (expired).
DynamoDB responds with success: the Burn is still applied because the read didn't filter expired items.

Practice

Your turn

A Burn should clear itself after 5 minutes. Add an ExpirationTime TTL attribute (epoch seconds) so DynamoDB can remove it asynchronously. Treat expired items as invalid in application reads until background deletion finishes.

Add ExpirationTime: Math.floor(Date.now() / 1000) + 300 to the item.

// @ts-nocheck
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: "ap-south-1" });
const docClient = DynamoDBDocumentClient.from(client);
async function applyBurn() {
  const command = new PutCommand({
    TableName: "StatusEffects",
    Item: {
      PokemonId: "Pikachu",
      Effect: "Burn",
      // ⬇️ Add a TTL attribute that expires 5 minutes (300s) from now, in
      //    epoch SECONDS. Hint: Math.floor(Date.now() / 1000) + 300
    },
  });
  await docClient.send(command);
  console.log("Burn applied — now eligible for asynchronous TTL cleanup.");
}

// @ts-nocheck
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb";

const client = new DynamoDBClient({ region: "ap-south-1" });
const docClient = DynamoDBDocumentClient.from(client);

async function applyBurn() {
  const command = new PutCommand({
    TableName: "StatusEffects",
    Item: {
      PokemonId: "Pikachu",
      Effect: "Burn",
      // ⬇️ Add a TTL attribute that expires 5 minutes (300s) from now, in
      //    epoch SECONDS. Hint: Math.floor(Date.now() / 1000) + 300

    },
  });

  await docClient.send(command);
  console.log("Burn applied — now eligible for asynchronous TTL cleanup.");
}

Ctrl/⌘ Enter to run · simulated, no AWS callsSimulated — no AWS calls

Check

Check your understanding

Quick Quiz · one question, as many tries as you need.

What format must the TTL attribute be in for DynamoDB to automatically delete the item?

Choose one answer.