Item Collection

An item collection is all the items in a DynamoDB table that share the same partition key value. If your table has a composite primary key (partition key + sort key), all items with pk = CUSTOMER#cust_01 form one item collection — regardless of their sort key values.

Why item collections matter

Two reasons:

1. The 10 GB limit. A single item collection cannot exceed 10 GB. If a partition key accumulates more than 10 GB of data, DynamoDB rejects writes to that partition with a ItemCollectionSizeLimitExceededException. In most applications this limit is theoretical. In single-table designs with extremely active partitions (a user who generates millions of events, a product with billions of purchase records), it can become real.

2. They define what a Query can return. A Query can only return items from a single item collection — items that share the same partition key. This is why single-table design co-locates related data under one partition key: to make multi-entity queries possible.

In single-table design

Single-table design intentionally builds large item collections. The CUSTOMER#<id> partition key creates an item collection that contains:

CUSTOMER#cust_01 / #METADATA          → customer record
CUSTOMER#cust_01 / ORDER#01HV...      → order 1
CUSTOMER#cust_01 / ORDER#01HU...      → order 2
CUSTOMER#cust_01 / ADDRESS#addr_01    → shipping address

All of these are one item collection. One Query can retrieve any subset. This is the feature single-table design is built around.

Monitoring collection size

The ReturnItemCollectionMetrics parameter on PutItem, UpdateItem, and DeleteItem returns the current size of the item collection. Use this in write-heavy partitions to detect growth before hitting the limit.

For partitions that genuinely approach 10 GB (time-series data, activity logs), design for horizontal sharding: use the user ID + a date shard in the partition key (USER#<id>#2026-05) rather than a pure user ID.

Local secondary indexes (LSIs)

Item collection size limits apply to LSIs too — the combined size of items in the main table and all LSIs for a given partition key cannot exceed 10 GB. This is one reason GSIs are generally preferred over LSIs for single-table designs: GSIs are counted separately.