DynamoDB Hot Partitions: How to Find and Fix Them
A hot partition is one partition key taking more reads or writes than a single partition can serve. Requests to that key throttle while the rest of the table sits idle.
What is a DynamoDB hot partition?
A DynamoDB hot partition is when one partition key absorbs far more reads or writes than its slice of throughput can serve, so requests to that key throttle while the rest of the table sits idle. The cause is key design (a celebrity item, a low-cardinality key, today's date), not table size. The cure is spreading the traffic.
- The ceiling is per partition: 3,000 read units and 1,000 write units per second, on provisioned and on-demand alike. Billing mode doesn't lift it.
- Find the key by name with CloudWatch Contributor Insights, and confirm
it's a partition limit with the
*KeyRangeThroughputThrottleEventsmetrics. - Shard write-hot keys with a suffix and read them back with one
Queryper shard. Cache read-hot items with DAX or a precomputed item. - A single item never splits. Adaptive capacity can spread a busy key's item collection, but one item stays capped at one partition's ceiling.
The per-partition ceiling
DynamoDB hashes the partition key to place each item on a physical partition. AWS designs each partition to deliver "a maximum capacity of 3,000 read units per second and 1,000 write units per second", in every billing mode (AWS: partition key design).
Your table's throughput is spread across all its partitions, so one busy key can throttle long before the table looks busy.
DynamoDB can split a busy partition in two at a sort-key boundary (split-for-heat), but not a single item, not an ever-increasing sort key, and not on a table with an LSI. How partitions split: physical partitions.
Name the trap: traffic that piles on one key
Throughput is shared evenly only if your access is spread evenly across keys. The moment one key gets disproportionate traffic, it throttles alone while the table's overall capacity goes unused.
Classic hot-key shapes:
- A celebrity item: one user, document, or tenant that everyone reads.
- A low-cardinality partition key:
status,country,type. Few distinct values means few partitions doing all the work. - A time-bucketed key:
PK = "2026-06-23". Every write today hammers one partition; yesterday's is cold forever.
Coming from SQL, a popular value in a B-tree index is fine; you only fight a hot row under lock contention. In DynamoDB the popular key value is the unit of physical placement, so popularity alone becomes a throughput cliff.
Diagnose it before you redesign
Throttling shows up as a ProvisionedThroughputExceededException or
ThrottlingException, and in CloudWatch as ThrottledRequests and
ReadThrottleEvents/WriteThrottleEvents. Two signals say a hot key is the cause:
ReadKeyRangeThroughputThrottleEvents/WriteKeyRangeThroughputThrottleEventscount requests "throttled due to partition limits". If those climb while*ProvisionedThroughputThrottleEventsstay flat, the table has capacity and one key range doesn't (AWS: CloudWatch metrics).- CloudWatch Contributor Insights for DynamoDB names the key. It ranks the most accessed and most throttled partition keys (and partition + sort key pairs) on a table or GSI, per minute.
Turn it on per table, and per GSI if the index is the hot side:
aws dynamodb update-contributor-insights --table-name Leaderboard \
--contributor-insights-action ENABLE \
--contributor-insights-mode THROTTLED_KEYSTHROTTLED_KEYS mode only processes (and bills) events when a request is
throttled, so you can leave it on.
ACCESSED_AND_THROTTLED_KEYS also ranks the busiest keys before they throttle, at a charge per item read or written
(AWS: Contributor Insights).
A GROUP BY on the partition key counts stored items, not traffic, so it can't
find a hot key. If the metrics point elsewhere (provisioned limits, account
quotas, an on-demand maximum), start from
the throttling guide.
A worked example: the global leaderboard
Say you run a gaming leaderboard. Every player's score lives under one key:
PK = "BOARD#global"
SK = "PLAYER#<playerId>"
After every match, the game bumps that player's score with an ADD. Every
write in the game lands on the single key BOARD#global. Past about 1,000 score
updates per second, the key throttles while every other board in the table is
idle.
Adaptive capacity may eventually split the collection by sort key, but that takes time and never happens on a table with an LSI. Sharding gives the headroom by design.
The footgun is the BOARD#global collapse: you modeled one logical board as
one physical key.
Spread the writes: write sharding
The fix is to manufacture cardinality. Append a shard suffix to the partition key so the board fans out across N key values. AWS documents two ways to pick the suffix (AWS: write sharding):
- Random suffix (
0…N-1at random): the most even spread, but you can't find one item again without querying every shard. Use it for append-only events or counters you sum on read. - Calculated suffix (a hash of something you query by, mod N): the same
player always lands on the same shard, so a
GetItemstill finds them.
The leaderboard needs the second kind:
PK = "BOARD#global#<shard>" -- shard = hash(playerId) mod 10
SK = "PLAYER#<playerId>"
Ten partition-key values are not ten physical partitions; two values can hash to the same one.
But DynamoDB can now place them apart, giving the board up to ten times one key's write ceiling. One player still writes to one item, capped at 1,000 write units per second.
See the difference for yourself. Paste a single repeated key into the visualizer
below and every write lands in one bucket. Add a shard suffix
(BOARD#global#0 … #9) and the same writes fan out evenly:
This is a teaching hash for intuition, not DynamoDB's real internal hash. The real function and partition boundaries are AWS internals. Read it as "even spread vs skew", not as a prediction of which physical partition a key lands on.
Write and read the sharded board
The write computes the shard; the read issues one Query per shard in parallel
and merges, because no single Query spans partition-key values. With the AWS
SDK for JavaScript v3:
import {DynamoDBClient, QueryCommand, UpdateItemCommand} from '@aws-sdk/client-dynamodb';
const client = new DynamoDBClient({});
const SHARDS = 10;
// Calculated suffix: the same player always lands on the same shard.
function shardOf(playerId) {
let h = 0;
for (const ch of playerId) h = (h * 31 + ch.codePointAt(0)) >>> 0;
return h % SHARDS;
}
async function addScore(playerId, points) {
await client.send(
new UpdateItemCommand({
TableName: 'Leaderboard',
Key: {PK: {S: `BOARD#global#${shardOf(playerId)}`}, SK: {S: `PLAYER#${playerId}`}},
UpdateExpression: 'ADD score :pts',
ExpressionAttributeValues: {':pts': {N: String(points)}}
})
);
}
async function topPlayers(n) {
const shards = await Promise.all(
Array.from({length: SHARDS}, async (_, shard) => {
const items = [];
let ExclusiveStartKey;
do {
const page = await client.send(
new QueryCommand({
TableName: 'Leaderboard',
KeyConditionExpression: 'PK = :pk',
ExpressionAttributeValues: {':pk': {S: `BOARD#global#${shard}`}},
ExclusiveStartKey
})
);
items.push(...page.Items);
ExclusiveStartKey = page.LastEvaluatedKey;
} while (ExclusiveStartKey);
return items;
})
);
return shards
.flat()
.sort((a, b) => Number(b.score.N) - Number(a.score.N))
.slice(0, n);
}topPlayers reads every player, so it's a job, not a page view. Run it on a
schedule and write the result to one BOARD#global / TOP#100 item. The sort
key orders items by player id, not score, so the top N can't come from a single
Query either way.
The key schema is the same key-overloading instinct behind single-table design: you shape the key for the access pattern, not for how the data "naturally" sits.
Fix the read side: cache the hot item
Sharding spreads writes. A read-hot item (the TOP#100 item every client
refreshes, a celebrity profile) is still one item on one partition. Sharding it
would multiply every read into N, so cache it instead:
- DynamoDB Accelerator (DAX) sits in front of the table with the same API. AWS names this case: "To mitigate the impacts of a 'hot' key and a non-uniform traffic distribution, you could offload the read activity to a DAX cache" (AWS: DAX).
- When DAX doesn't fit: it serves eventually consistent reads only and passes strongly consistent ones through, it suits read-heavy rather than write-heavy items, and AWS says it "performs best when cache hit rates exceed 90%".
- Without DAX, cache the item in your application or a CDN for a few seconds. A leaderboard rarely needs to be fresher than that.
Let adaptive capacity do the easy part
Adaptive capacity shifts a table's throughput toward the partitions taking heat, instantly and at no cost, on both billing modes, and can isolate a frequently accessed item onto its own partition (AWS: bursting and adaptive capacity).
It can't lift the per-item ceiling, and split-for-heat is slower and not guaranteed, so don't wait on it. How it decides: adaptive capacity.
Decision path once you see throttles on a busy key:
Raise the traffic on the hot key below to watch one partition's load climb past the per-partition ceiling while its neighbors sit idle. Throttling starts well before the table-level numbers look busy:
Pitfalls to avoid
- Ever-increasing sort keys. A monotonic sort key (a timestamp, a sequence
number) sends every new write to the same end of one item collection, so
split-for-heat can't help and the key stays capped at 1,000 write units.
Shard the partition key. A random prefix on the sort key would still rely on
split-for-heat (never with an LSI) and would break time-range
Querys on it. - Sharding a read-hot item. If reads dominate, sharding multiplies them. Cache the item (above). A GSI with a better-distributed key helps only when many items share a low-cardinality key, not for a single hot item.
- Confusing a hot partition with a slow
Scan. AScanis slow because it reads everything; a hot partition throttles because one key is overloaded. Different problems: see Query vs Scan.
Next steps
Sketch the sharded keys, then prove the read path against real data.
The DynamoDB Expression Builder emits each shard's
KeyConditionExpression with its name and value maps; change the shard value per
query. Then download DynoTable to run each shard's query against your
own tables and compare the items with what your merge returns.