DynamoDB physical partitions
A physical partition is the unit DynamoDB stores your data on: an allocation of SSD storage, replicated across Availability Zones, holding one slice of your key space.
Your table is a logical thing; partitions are where the bytes and the throughput limits live.
How do DynamoDB partitions work?
The hash of your partition key decides which partition an item lands on.
Each partition caps at about 10 GB, 3,000 read units/sec and 1,000 write units/sec, and DynamoDB adds partitions as you raise throughput, as partitions fill, and as they run hot.
- The ceilings are per partition, not per table. A table provisioned far above 1,000 WCU still throttles when the writes land on one partition.
- Items with the same partition key land together. Traffic on one item, or on the leading edge of a monotonic sort key, stays on one partition.
- DynamoDB splits partitions for you, on size and on sustained traffic. It can split one key's item collection by sort key, unless an LSI or an ever-increasing sort key blocks it.
- Throttling with capacity to spare is the tell. Throttling while the table sits at 5% usage usually means one partition is maxed out; the exception's throttle reason confirms it.
How an item finds its partition
DynamoDB feeds your partition-key value through an internal hash function, and the hash output picks the physical partition. Same key in, same partition out, until that key's item collection grows or heats enough to split; then the sort key decides which slice holds the item.
Coming from SQL, you may expect to tune an index or assign a shard key range by hand. Here the placement is a hash you don't control and never see.
Items sharing a partition key form an item collection, stored together and
sorted by sort key. That's what makes a Query on one key cheap: it reads one
contiguous run in sort-key order. (See Query vs Scan.)
Take a match-event store for a game. The table keys are arenaId (partition) and
eventKey (sort):
# Item
arenaId = "ARENA#7f3a"
eventKey = "EVT#1719100800#a91c"
playerTag = "Nightjar"
dmgDealt = 412
Every event for arena 7f3a shares one partition key, so it lands in one item
collection, stored in sort-key order. Great for "read this match's timeline." A liability if that one arena gets
all the traffic.
The three ceilings every partition enforces
A single partition is designed to deliver at most:
| Limit | Per partition | Counted as |
|---|---|---|
| Storage | ~10 GB | Items, plus any LSI entries stored alongside them |
| Read capacity | 3,000 read units/sec | 1 RU = one strongly consistent read of up to 4 KB |
| Write capacity | 1,000 write units/sec | 1 WU = one write of up to 1 KB |
Sources: AWS Best practices for designing partition keys for the read and write rows, and Constraints ("10GB is the maximum size of a partition") for storage.
Item size scales the math. A 20 KB item costs 5 read units per strongly consistent read, so one partition serves ~600 such reads/sec before it throttles, not 3,000. Round write cost up per 1 KB, read cost up per 4 KB.
Those caps are per partition, not per table. Your table can be provisioned for 40,000 WCU and still throttle, because all the writes are pounding one partition that tops out at 1,000.
How partitions split
AWS lists two situations in which DynamoDB allocates more partitions: you raise provisioned throughput beyond what the existing partitions support, or a partition fills up.
A third, split for heat, follows sustained traffic. Only the first is something you do.
Split on size. When a partition fills toward ~10 GB, DynamoDB splits its key range and moves part of the items to a new partition. Your table stays available throughout.
Split for heat. When a partition's consumed throughput crosses a threshold, DynamoDB splits it. The 2022 USENIX ATC paper says the split point "is chosen based on key distribution the partition has observed", not the middle of the range.
Throttling that stops on its own often means a split happened, though a short spike that outran burst capacity and then ended looks the same.
Splitting buys room across many keys, and split for heat can even carve one key's item collection at a sort-key cut. What it can't spread is a single hot item, an ever-increasing sort key, or a collection pinned by an LSI.
Why a hot key beats the splitter
Splitting divides key ranges. If your traffic concentrates on one item, or on the leading edge of a monotonic sort key, every request lands in the same narrow range and there's nothing useful to carve off.
Say arena 7f3a is a tournament final pulling 4,000 writes/sec while every other arena is idle.
You'll throttle at 1,000 write units/sec, and split for heat can't help: the timestamp-prefixed eventKey is monotonic, so every new write lands at the leading edge of one sort-key range.
The throttling exception tells you this is the case. Its ThrottlingReasons field names
a TableWriteKeyRangeThroughputExceeded (or TableReadKeyRangeThroughputExceeded)
reason: one partition's key range, not the table, is over its limit.
An Index…KeyRange… reason points at a GSI instead. Throttling
maps every reason to its fix.
To name the key, turn on CloudWatch Contributor Insights for the table or GSI. Its throttled-keys mode is cheap enough to leave on and lists the most-throttled partition keys.
The fix is in the data model, not the capacity slider. Write-shard the hot key by appending a small suffix, so one logical arena spreads across several partition keys. Hot partitions covers picking the suffix and reading the shards back.
Prototype the suffixed key and its Query in the Expression Builder.
One nuance: the LSI exception
There's one case where storage is capped per partition key.
Without a Local Secondary Index, an item collection splits across as many partitions as it needs to serve both its stored bytes and its throughput (split for heat still can't divide one item or spread a monotonic sort key's leading edge), and billions of sort-key values are fine.
Add an LSI, and the whole collection for one partition key, including the LSI's projected entries, must fit in one 10 GB partition.
Past that, writes that grow the collection can fail with ItemCollectionSizeLimitExceededException. That's the per-PK cliff covered in GSI vs LSI.
If your table already has an LSI, set ReturnItemCollectionMetrics: SIZE on writes and alert well below the cap (AWS suggests 8 GB). Near it, delete or trim items in that collection.
For collections that can grow without bound, AWS recommends a GSI: that means a new table without the LSI and a data move, since LSIs exist only from CreateTable.
Designing so partitions stay cool
The partition key is what you control. Pick one with many distinct values relative to item count, so traffic spreads evenly. (More patterns in single-table design.)
- Use a high-cardinality key. A per-user or per-tenant key beats a per-day or per-status key that everyone hits at once.
- Watch for known hot keys. A "current tournament" or "today" value is a concentration risk before you ship, not after.
- Shard the unavoidable hot key. When one key must take outsized traffic, a suffix spreads it, and adaptive capacity covers the skew short of that.
For traffic, rely on Contributor Insights, as above.
To see which keys hold the most items (collection size, which is what the 10 GB LSI cap
watches), point DynoTable at your table and GROUP BY the partition key in the
SQL Workbench.