DynamoDB TTL attribute must be a Number

TL;DR — DynamoDB 的 Time to Live 只在項目的指定 TTL 屬性持有代表 Unix epoch 秒時間戳的 Number 時才刪除它。像 "1735689600" 這樣的字串、毫秒值、ISO-8601 日期,或缺少屬性,都會被默默忽略 — 項目永不過期。將 TTL 儲存為 epoch 秒 Number 並重寫受影響的項目。

這是什麼意思

# A second UpdateTimeToLive call within one hour of the first raises:
ValidationException  (TTL settings can only be modified once per table per hour)

# The quieter failure — no error at all, item just never expires:
TTL attribute "expiresAt" = "2026-01-01T00:00:00Z"   ← String, ignored
TTL attribute "expiresAt" = 1735689600000            ← milliseconds: tens of thousands of years away

啟用 TTL（UpdateTimeToLive）即使在屬性尚不存在或型別錯誤時也會成功 — DynamoDB 不會事先型別檢查它。失敗稍後才出現:背景 TTL 程序只在屬性是持有過去（且不超過五年前）Unix epoch 秒時間戳的 Number 時才刪除項目。其他任何東西都被視為「無過期」。

為什麼會發生

儲存為字串 — 值是 {"S": "1735689600"} 而非 {"N": "1735689600"}。TTL 忽略非 N 型別。
毫秒而非秒 — Date.now()（JavaScript）回傳毫秒;一個 13 位數的值是數萬年後的未來,因此項目實際上永不過期。
ISO-8601 / 人類日期字串而非 epoch 秒。
超過五年前的時間戳 — TTL 程序會忽略它而非刪除項目。
與註冊給 TTL 的名稱不同的屬性名稱（名稱區分大小寫）。
太快再次呼叫 UpdateTimeToLive — 變更需時最多一小時完全處理,而在那一小時內對同一表格的任何額外 UpdateTimeToLive 呼叫都會引發 ValidationException。

如何修正

將 TTL 值寫成 epoch 秒的 Number — JavaScript 中 Math.floor(Date.now() / 1000) + ttlSeconds,Python 中 int(time.time()) + ttl。絕不儲存毫秒。
使用 N 型別,而非 S。用低階用戶端是 {"N": "1735689600"};Document Client 為你 marshal 原生數字。
精確匹配註冊的屬性名稱,包括大小寫。以 DescribeTimeToLive 確認它。
回填既有項目 — 修正前寫入的項目仍攜帶錯誤的值;以正確的 epoch 秒 Number 重寫它們。
在 TTL 設定變更之間等待一小時 — UpdateTimeToLive 需時最多一小時處理,而在該視窗內的進一步呼叫會以 ValidationException 被拒絕。

想在瀏覽表格時看到每個屬性的線路型別?DynoTable 桌面應用程式內嵌呈現 N/S/M 型別標記,因此存為字串的 TTL 在它讓你損失一個未過期項目前就跳出來。

常見問題

為什麼我的 DynamoDB TTL 沒有刪除項目? TTL 屬性必須是持有 Unix epoch 秒時間戳的 Number。字串值、毫秒值、ISO 日期,或與註冊 TTL 屬性不符的名稱,全都被默默忽略,因此項目永不過期。刪除也不是立即的 — DynamoDB 通常在過期時間後數天內移除過期項目。

我啟用 TTL 時 DynamoDB 會驗證 TTL 屬性型別嗎? 不會。UpdateTimeToLive 即使屬性缺少或型別錯誤也會成功。型別需求（Number、epoch 秒）只由背景刪除程序強制執行,這就是為什麼錯誤的 TTL 安靜地失敗。

參考資料

最後驗證於 2026-07-13，對照上方連結的 AWS 官方文件。