Advanced8 min read

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 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 , 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:

LimitPer partitionCounted as
Storage~10 GBItems, plus any LSI entries stored alongside them
Read capacity3,000 read units/sec1 RU = one strongly consistent read of up to 4 KB
Write capacity1,000 write units/sec1 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.

SizeHeatPartition A~10 GB / hotSplittrigger?Range splitby sizeRange split at observedkey distributionTwo partitionsown capacity eachOne hot ITEMstill on one partition

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.

How partitions split, live
24 GB
30 %

Grow the table and ranges halve by bytes — every new partition brings its own capacity. Raise the hot key’s traffic past what one partition serves, and split-for-heat carves its neighborhood out.

The flame marks the partition the hot key ARENA#7f3a hashes to. Width is stored GB; tint is the share of read traffic.

4 partitions after 3 splits, each with its own 3,000 RCU/s ceiling — yet the hot key ARENA#7f3a still rides only P1, which serves 1,850 RCU/s.

PartitionKey rangeStored (GB)TrafficReads (RCU/s)Born of
P1holds the hot key ARENA#7f3a0–25%655.2%1,850Original
P225–50%614.9%500Size split
P350–75%614.9%500Size split
P475–100%614.9%500Size split

Per-partition ceilings: ~10 GB stored, 3,000 read units/s and 1,000 write units/s — splits add partitions, never a bigger one.

This is a simplified teaching hash, not DynamoDB’s real internal hash. DynamoDB uses an undocumented internal function and a partition count that grows with your table — use this only to build intuition for how distinct keys spread and a single hot key piles up.

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 , 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.

By Dmitriy · Updated