Intermediate11 min read

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 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 *KeyRangeThroughputThrottleEvents metrics.
  • Shard write-hot keys with a suffix and read them back with one Query per 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 / WriteKeyRangeThroughputThrottleEvents count requests "throttled due to partition limits". If those climb while *ProvisionedThroughputThrottleEvents stay 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_KEYS

THROTTLED_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-1 at 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 GetItem still 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:

Partition-key distribution

One partition-key value per line. Repeat a value to simulate a hot key.

8 buckets8 keys
  • #0
    1
  • #1
    2
  • #2
    0
  • #3
    0
  • #4
    2
  • #5
    2
  • #6
    0
  • #7
    1

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.

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

ReadsWritesOne itemMany items,one keyThrottling onone key?Reads orwrites?Cache the item(DAX / app cache)One item ormany items?Shard the item(sum on read)Shard thepartition 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:

Partition load and throttling
6,000 RCU/s
500 WCU/s
60 %

The skewed share of all traffic lands on the single hot key USER#1000, which hashes to partition #2; the rest spreads evenly over 24 keys.

Hottest partition: #2 with 65% of the traffic — 1 of 8 partitions over a per-partition ceiling.

PartitionKeysTrafficReads (RCU/s)Writes (WCU/s)Status
#046.7%40033OK
#135%30025OK
#2365%3,900325Reads throttled
#346.7%40033OK
#423.3%20017OK
#535%30025OK
#635%30025OK
#723.3%20017OK

Per-partition ceilings: 3,000 read units/s and 1,000 write units/s — a single physical partition never serves more, regardless of what the table has provisioned.

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.

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. A Scan is 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.

By Dmitriy · Updated