Hide outline
Feedback
Guide
Was this lesson helpful?
Dive Deeper
Generate a follow-up sub-lesson on any aspect of this topic
Guide complete
DynamoDB Partitioning And Capacity Internals
Generate a follow-up sub-lesson on any aspect of this topic
DynamoDB Partitioning And Capacity Internals
TLDR;
- A table can show plenty of headroom while one partition silently hits its per-partition cap and throttles.
- Partition splits happen for different reasons, and only some splits actually relieve hot-key pressure.
- Burst capacity and adaptive capacity help different spike shapes, with different observability signatures.
A PutItem workload for a multi-tenant API can look healthy at the table level while a single tenant key intermittently returns ProvisionedThroughputExceededException and p99 latency jumps.
Operationally, a hot partition is a physical partition that is receiving more read or write traffic than its independently enforced per-partition throughput allows, so requests to that partition throttle even if other partitions are idle.
The fastest way to recognize this pattern is to align CloudWatch ThrottledRequests with ConsumedReadCapacityUnits or ConsumedWriteCapacityUnits and notice that throttling correlates with a specific access pattern rather than with overall table consumption.
To make that correlation concrete, let’s inspect a time-aligned view of consumption versus throttles.
DynamoDB enforces throughput at multiple scopes, including table-level limits and per-partition limits, so throttling can occur due to a single partition saturating before the table saturates.
When per-partition saturation is the cause, the tell is that Consumed* stays below Provisioned* at the table level while ThrottledRequests climbs during bursts that target a narrow key range, often one partition key value or one item collection.
Two workload shapes commonly trigger this even with high provisioned capacity. One is a “single-tenant” partition key where all writes for that tenant map to one physical partition for a while, and the other is a time-ordered sort key pattern where the hottest items cluster at the end of the sort key range.
Evidence boundary CloudWatch metrics and service errors confirm that throttling occurred, but they do not directly reveal physical partition boundaries. Inferring hot partitions is a correlation exercise across request patterns, item keys, and throttle timing.
A DynamoDB table is split into “partitions”, which are internal storage and throughput units assigned to storage nodes, and DynamoDB routes requests through a front-end tier that uses partition metadata to reach the correct replica group.
The partition key is hashed, and that hash is used to map items into a key space that is owned by physical partitions. With a sort key, items are additionally ordered within the item collection, which is why range-like traffic on the sort key can concentrate heat even when partition key values look diverse.
Even “even-looking” partition keys can still be hot because uniform key distribution is not the same as uniform access distribution. A small fraction of keys often accounts for most requests, and physical partitions are managed independently, so one partition can hit limits while others remain underutilized.
A second trap is assuming that a table with many partition key values automatically spreads traffic. If the workload repeatedly targets a narrow subset of those values within a short window, hashing cannot help because the problem is not placement entropy, it is concentrated demand.
DynamoDB can increase the number of physical partitions backing a table, but the reason matters because it changes what gets redistributed and how quickly throttling pressure is relieved.
Split-for-size is driven by growth in stored data, and common guidance is that a partition is associated with limits like 10 GB of data and per-partition throughput ceilings that are often summarized as 3,000 RCUs and 1,000 WCUs. Those numbers are useful for reasoning about worst-case throttling even though internal behavior can be more nuanced.
Split-for-heat is an adaptive response to sustained imbalance where DynamoDB may split a hot partition to isolate frequently accessed items, increasing the throughput available to the hot working set while staying within the table’s total capacity and the per-partition maximums.
What “moves” during a split is not an application-visible reshuffle of item keys. Internally, DynamoDB changes partition ownership of parts of the key space and relocates responsibility so that traffic can be served by more resources, which is why split-for-heat can double observed throughput for a targeted workload over time.
Timing risk matters. Split-for-heat is reactive and can involve brief service-side turbulence during cutover, so treating it as an automatic fix for an ongoing incident can be unsafe. The safer stance is to design keys so a single tenant or time window cannot pin all writes to one partition for long.
Before we lock in the mental model, let’s predict how each split type changes throttling.
DynamoDB uses burst capacity to temporarily allow higher throughput by saving some unused capacity for later spikes, and AWS documentation notes it retains up to five minutes of unused read and write capacity for this purpose.
Burst helps when a workload is normally below provisioned capacity but has short spikes. It is not guaranteed because DynamoDB may consume burst capacity for internal maintenance, and the details are explicitly stated as subject to change.
Adaptive capacity is an automatic mechanism that increases throughput for partitions receiving more traffic, within the constraints of table capacity and per-partition maximums, and can also isolate frequently accessed items so they do not share a partition with other hot items.
A practical way to distinguish them is by timescale and persistence. Burst smooths sudden spikes until credits deplete, while adaptive capacity aims to make sustained imbalance work by changing capacity allocation and sometimes repartitioning so the hot working set no longer contends with unrelated keys.
To compare the two mechanisms without handwaving, let’s line up their triggers, constraints, and signals.
The most reliable mitigation is to make the partition key represent a high-cardinality, high-entropy dimension of the write load, so no single partition key value can dominate total traffic for long. In practice that usually means avoiding designs like tenantId alone when tenant traffic is spiky.
A common pattern is write sharding, where a synthetic suffix spreads writes across partition key values, such as tenantId#00 to tenantId#15, while reads either query multiple shards in parallel or maintain a small fanout index. The cost is added read complexity and potentially higher read capacity usage.
For time-series like events or counters, time-bucketing spreads heat by encoding a time window into the partition key, such as tenantId#2026-10-16T12 for hourly buckets. This bounds the maximum write rate per bucket and gives a predictable archival and TTL story.
Composite keys matter because split-for-heat can use the sort key to separate traffic within one partition key value in some cases, but the AWS documentation cautions that adaptive capacity will not split item collections across multiple partitions when the table has a local secondary index. Treat LSIs as a commitment that can reduce future partition flexibility.
Global secondary indexes can absorb alternate query patterns, but they can also create their own hot partitions if the GSI partition key is low-cardinality or time-ordered. Any key change rollout should include dual writes, backfill validation, and a throttling canary on the new key space before cutover.
Start from user impact and observed evidence. Capture the exact API operations, item sizes, and key patterns that correlate with ThrottledRequests, then check whether the throttle aligns with a narrow partition key set or a narrow sort key range.
Validate the scope of the limit being hit.
Consumed* is near Provisioned* or account table limits, mitigate with capacity changes, on-demand mode where appropriate, or request quota increases.Choose mitigations that match the spike shape and residual risk.
Consumed* rather than trusting pre-change estimates.Decision rule When throttling happens with table headroom, assume per-partition saturation until a key redesign disproves it.
Next step is to pick one top throttled access path, write down its partition key and sort key shape, then decide whether the right fix is spreading traffic in space with sharding or in time with bucketing.