中級読了 2 分

DynamoDB TTL:期限切れアイテムが削除される仕組み

Time to Live(TTL) は、あなたがアイテムに保存したタイムスタンプが過ぎると、DynamoDB がそのアイテムを自動的に削除できるようにします。Unix エポックの有効期限を保持する 1 つの属性を指定すると、DynamoDB は期限切れのアイテムをバックグラウンドで削除します。自前の削除ジョブは不要で、書き込みキャパシティも消費しません。

マルチテナント SaaS の追記専用の監査ログを例にしましょう。テナントのパーティションキー(PK = TENANT#acme)の下に、イベントごとに 1 アイテムを置きます。各テナントには保持ポリシーがあります。イベントを 90 日間、1 年間、あるいはコンプライアンス重視のテナントなら 7 年間保持する、というように。TTL は、自前の削除スイープなしでそれを強制します。

DynamoDB TTL はどのように機能するのか?

テーブルで TTL を有効にして 1 つの属性を指定すると、DynamoDB は各アイテムを、その属性のタイムスタンプが過ぎてからしばらく後に削除します。

  • TTL は Unix エポック(秒)のタイムスタンプを保持する 1 つの属性。 その時刻が過ぎると、アイテムは削除の対象になります。
  • 削除はバックグラウンドかつベストエフォート: 通常は期限切れから数日以内であって、正確な秒ではありません。
  • TTL の削除は無料。 書き込みキャパシティを消費しません。ただし、グローバルテーブルでは、複製された削除が他のすべてのレプリカリージョンで書き込み 1 回分のコストになります。
  • 期限切れだがまだ削除されていないアイテムは読み取りに依然として現れるので、すぐに隠したい場合は有効期限の属性でフィルタリングしましょう。

問題: 古いデータを自前で期限切れにするのは高コスト

TTL がないと、「90 日より古いイベントを削除する」を強制するには、自前の削除処理を走らせることになります。スケジュールで古いアイテムをスキャン(またはクエリ)し、それぞれを DeleteItem します。そのスキャンは読み取りキャパシティを消費し、削除は書き込みキャパシティを消費し、スケジュール、失敗、再試行もあなたが抱えることになります。

大量の監査ログでは、そのコストは保持するイベントが増えるたびに膨らみます。TTL はその仕事を DynamoDB に移し、削除は無料になります。

TTL の仕組み

テーブルで TTL を有効にし、どの属性が有効期限を保持するかを指定します。

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

値は、Unix エポック時刻を秒で保持する Number でなければなりません。TTL は、属性が Number でないアイテムと、値が 5 年以上過去のアイテムを無視します(TTL の計算)。

TTL のドキュメントによれば、DynamoDB は "automatically deletes expired items within a few days of their expiration time, without consuming write throughput" とされています。それまでは、期限切れのアイテムも読み取れますし、更新もできます。TTL 属性を未来の時刻に設定するか削除すれば、そのアイテムは削除されません。

その更新には attribute_exists(PK) のような条件を付けてください。条件がないと、TTL がアイテムを削除した後に届いた更新は、その更新が設定する属性だけを持つアイテムを再作成してしまいます。

実例: テナントごとの保持

各監査イベントは、イベントが書き込まれたときに設定される expiresAt 属性を持ちます。値は now + テナントの保持ウィンドウ で、エポック秒です。

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

expiresAt で TTL を有効にすると、acme の 90 日イベントは時刻が 1782259200 を過ぎた時点で削除の対象になり、DynamoDB が通常は数日以内にひとりでに削除します。

コンプライアンステナントのイベントは遥か未来の expiresAt を持つので、残り続けます。同じテーブル、同じ仕組みで、アイテムごとに異なる保持です。

書き込み側は、イベントを作成するときに 1 つの数値を追加するだけです。SET expiresAt = :ttl 句を組み立て、型付きの :ttl 値を DynamoDB Expression Builder で検証できます。

期限切れだがまだ削除されていないイベントを読み取りから即座に隠すには、クエリの FilterExpression に expiresAt > :now を追加します。フィルターは読み取りコストを減らしません(Query と Scan)。

監査イベントはすべて expiresAt を持ちます。expiresAt を持たないアイテムがあるテーブルでは、attribute_not_exists(expiresAt) OR expiresAt > :now を使います。

期限切れアイテムをアーカイブする

TTL が削除する各イベントのコピーを残すには、ストリームから削除を読み取ります。削除レコードがアイテムを運ぶように OLD_IMAGE(または NEW_AND_OLD_IMAGES)でストリームを有効にし、TTL による削除だけに一致するフィルターを持つ Lambda を接続します(TTL と 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\"]}}"}]}'

このフィルターは AWS の TTL と Streams のページが公開しているものなので、そのまま使ってください。ただし、Lambda の DynamoDB フィルタリングのページには、イベントソースマッピングは "only support filtering on the dynamodb key" と書かれています。

2 つのページの記述が食い違っているので、フィルターを唯一のゲートにはできません。関数自身が null 安全にマーカーを確認する必要があります。ユーザーによる書き込みや削除には 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
  }
};

この経路は DynamoDB Local ではテストできません。Local の TTL 削除レコードには userIdentity がないため、このチェックがスキップしてしまいます。

レコードはアイテムが消えた後に届き、ストリームはそれを 24 時間保持します。それより長く停止したコンシューマーはそれらのアイテムを失います。障害時の設定と、より長く保持する方法は Streams ガイドで解説しています。グローバルテーブルでは、削除を実行したリージョンだけがレコードにマーカーを付けます。

DynoTable でやってみる

古典的な TTL のバグは、間違った expiresAt です。秒の代わりにミリ秒で、あるいは ISO 文字列として保存されていると、どちらの場合もアイテムは決して期限切れになりません。ミリ秒の値は約 56,000 年先の日付として読まれ、TTL は String を無視します。

DynoTable は各アイテムの属性を DynamoDB の型とともに表示するので、expiresAt がエポック 秒 の Number であること(String でも、ミリ秒でもないこと)を、実際の保持を TTL に託す前に確認できます。

DynoTable で監査イベントの expiresAt 属性が Unix エポック秒の Number であること(TTL が作用する唯一の値)を検証する様子。
DynoTable で監査イベントの expiresAt 属性が Unix エポック秒の Number であること(TTL が作用する唯一の値)を検証する様子。

落とし穴と次のステップ

  • エポック秒、Number として。 ミリ秒の値は有効期限を約 56,000 年先へ押しやり、ISO 文字列は完全に無視されます。値を TTL コンバーターに貼り付けてください。秒とミリ秒を検出し、まさにこのミスを指摘します。
  • すでに間違って書き込まれたアイテムを修復する。 書き込み側を直しても、保存済みのアイテムは変わりません。expiresAt > :ms(:ms = 100000000000、秒として読むと 5138 年)または attribute_type(expiresAt, :s)(:s = "S")で Scan して見つけ、それぞれに秒単位の正しい値で SET expiresAt します。
  • バックフィルは過去に寄りすぎることがある。 古いイベントに createdAt + retention を設定するバックフィルは、5 年以上過去の値を生むことがあり、TTL はそれを無視します。そうしたイベントは直接削除してください。
  • 削除のタイミングに頼らない。 期限切れから削除までに数日が経つことがあります。期限切れのアイテムを隠すには、読み取りで属性をフィルタリングしましょう。削除を期限どおりに行い、それを証明する必要があるなら、期限切れの範囲を Query するスケジュールジョブから期限の時点で DeleteItem(または BatchWriteItem)で自分で削除してログに残し、TTL はバックストップにします。ストリームハンドラーはこれらの削除をユーザーによる書き込みとしてスキップするので、アーカイブもするなら、ジョブは Query した各アイテムを削除する前にアーカイブへ書き込みます。ジョブの読み取りと削除の間に TTL がアイテムを削除すると、両方の経路がそれをアーカイブするので、アーカイブする各オブジェクトはアイテムのプライマリキーをキーにしてください(キーごとの S3 オブジェクトなら重複は上書きされます。Firehose ストリームでは下流での重複排除が必要です)。
  • TTL の削除は にも及ぶ。 アイテムを削除すると、それが入っていたセカンダリインデックスからも削除されます。件数がライブアイテムを追跡しなければならないなら、インデックスを数えるのではなく、ストリームから維持してください(TTL による削除も含め、各 REMOVE レコードでデクリメントします)。

TTL はイベントのライフサイクルの終わりを安価に処理します。次の疑問は、そもそも書き込みに何を支払うのかです: オンデマンド対プロビジョンドキャパシティ。

DynoTable をダウンロードして、アイテムの属性の型を検査し、TTL をオンにする前に、TTL 属性が Unix エポックの Number であることを確認しましょう。

著者: Dmitriy · 更新日