DynamoDB LSI item collection 10 GB limit
TL;DR — 在一张带本地二级索引的表上，一个_项目集合_——每个共享一个分区键的项目，加上它们的 LSI 投影——合计最多 10 GB。只有 LSI 表才有这个上限，因为每个项目集合必须容纳在单个分区上。一次会把集合推过 10 GB 的写入会以 ItemCollectionSizeLimitExceededException 失败。监控 ItemCollectionMetrics、重新分片增长的键，或者用 GSI（它没有这样的限制）替换 LSI。
含义
ItemCollectionSizeLimitExceededException: Collection size exceeded.一个项目集合是表及其所有 LSI 中具有相同分区键值的所有项目的集合。当一张表有 LSI 时，DynamoDB 把每个项目集合存储在单个分区上，因此集合受该分区 10 GB 容量的限制。没有 LSI 的表没有逐集合的大小限制（GSI 也没有）。所以这个错误是一个信号：某个分区键的数据在一个 LSI 下无界地增长了。它是一个 HTTP 400；AWS 把它列为可重试，但重试只有在集合缩小后才会成功——读取和缩减大小的写入（删除、修剪属性）仍然被允许。
为什么会发生
- 一个无界的分区键——一个大租户、一个繁忙的用户，或一个仅追加的日志都在一个键下写入。
- LSI 本身——10 GB 上限_只_因为表有一个 LSI 才存在（在表创建时创建且不可移除）。
- 宽的 LSI 投影——把许多属性投影进 LSI 会更快地膨胀集合。
- 稳步增长，悄悄逼近 10 GB，直到一次写入最终越过它。
如何修复
- 重新分片分区键。 把过大的实体跨多个键拆分（
TENANT#42#1、TENANT#42#2……），使得没有单个集合无界地增长。 - 用 GSI 替换 LSI。 GSI 有它们自己的分区键且没有项目集合大小限制——对大多数访问模式而言，GSI 更合适，而且它可以在表创建后添加/移除（LSI 不行）。
- 修剪 LSI 投影——如果你必须保留 LSI，就投影更少的属性（
KEYS_ONLY/INCLUDE）以减缓集合增长。 - 把冷项目归档出热集合到另一张表或 S3。
- 在撞墙之前监控。 在写入（
PutItem、UpdateItem、DeleteItem、BatchWriteItem、TransactWriteItems）上设置ReturnItemCollectionMetrics: SIZE；DynamoDB 会返回一个SizeEstimateRangeGB估计值，AWS 建议在一个用户定义的阈值（例如 8 GB）上告警，让你在 10 GB 之前采取行动。
在重做键和索引以摆脱 LSI 限制？DynoTable 桌面应用让你按分区键过滤，这样你就能在重新分片之前看到哪个集合过大了。
从 DynoTable
找到接近 10 GB 的分区键 — 使用 ⌘K 打开表，按分区键排序，并对每个集合的项目进行计数。当广泛的 LSI 预测导致馆藏膨胀时，item size calculator 估计会出现增长。将 LSI 写入成本与 GSI 迁移与 pricing calculator 进行比较。使用 ⌘P 切换配置文件；参见连接 AWS和安装。
来源
- Local secondary indexes（2026-07-13 验证）
- PutItem — Amazon DynamoDB API Reference（2026-07-13 验证）
相关错误
- ItemCollectionSizeLimitExceededException——同一个异常，带通用的容量框架。
- Item size has exceeded the maximum allowed size——单独的每项目 400 KB 上限。
- 学习：Item collections · GSI vs LSI · 索引
参考资料
- Local secondary indexes — Amazon DynamoDB Developer Guide
- Error handling with DynamoDB — Amazon DynamoDB Developer Guide
- Quotas in Amazon DynamoDB — Amazon DynamoDB Developer Guide
- PutItem — Amazon DynamoDB API Reference
最后核实于 2026-07-13，依据上方链接的 AWS 官方文档。