Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 37 ยท Data Model and Keys

How DynamoDB Partitions Your Data

See how DynamoDB spreads items over partitions with a hash of the partition key, how partitions split, the per-partition limits, and what adaptive capacity does.

A DynamoDB table looks like one logical thing, but underneath it is a set of partitions, each a slice of storage with its own throughput. Understanding how items are assigned to partitions explains almost every performance rule in the service: why key choice matters, why a "hot" key can throttle you even when the table has spare capacity, and why a Query is fast.

You never manage partitions yourself. DynamoDB creates, splits and moves them automatically. But your partition key values decide how evenly your data and traffic spread across them.

The hashing step

When you write an item, DynamoDB applies an internal hash function to its partition key value. The hash output maps to a point in a range of hash values, and each partition owns a contiguous slice of that range. The item goes to whichever partition owns its hash.

Consequences:

  • The hash scrambles the key, so keys that look alike (u-1001, u-1002) land on different partitions. There is no way to keep "neighbouring" partition keys together.
  • Every item with the same partition key hashes to the same place, so a collection stays together.
  • Within a partition, items with the same partition key are kept in sort key order (a B-tree), which is why range queries on the sort key are cheap.
flowchart TB
    K["Partition key value"] --> H["Internal hash"]
    H --> R{"Which hash range?"}
    R -->|"0 - 33%"| P1["Partition A"]
    R -->|"33 - 66%"| P2["Partition B"]
    R -->|"66 - 100%"| P3["Partition C"]

Partition limits

Each partition has limits, which are what make the service predictable:

Limit Value (approximately)
Storage per partition about 10 GB
Read throughput per partition up to 3,000 read capacity units per second
Write throughput per partition up to 1,000 write capacity units per second

A table starts with enough partitions for its provisioned or recent on-demand throughput and for its size. As it grows or as traffic grows, DynamoDB splits partitions: one partition becomes two, each owning half of the hash range, and items are redistributed. Splits are invisible to your application.

One important exception: when a table has a local secondary index, an item collection (all items with one partition key, across the table and its local indexes) cannot exceed 10 GB. Without local secondary indexes, a single partition key can hold more data across partitions of its sort-key range.

Hot partitions

Throughput is not shared perfectly across a table. If most traffic targets a single partition key value, all of it lands on one partition, and that partition's per-second limit applies no matter how many partitions exist. The result is throttling (ProvisionedThroughputExceededException in provisioned mode, or throttled requests in on-demand mode) while the rest of the table sits idle.

This is the "hot key" or "hot partition" problem. Typical causes:

  • a partition key with few distinct values (Status = "active"),
  • a key that is a date, so today's writes all hit one partition,
  • a celebrity user, popular product or viral item.

Adaptive capacity

DynamoDB applies adaptive capacity automatically. It can shift throughput towards busy partitions and, in recent versions of the service, even isolate a frequently accessed item onto its own partition. This forgives uneven traffic, but it does not remove the hard limits: one item or one partition key can still be limited to roughly 3,000 reads or 1,000 writes per second. Good key design remains your job.

Simulating hash placement

This stand-in uses a stable hash to place keys on partitions and then measures how evenly a workload spreads. It is a model of the principle, not the real hash.

Python Stand-in: even keys vs one hot key

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

In the first run the load is roughly one eighth per partition. In the second, one partition carries everything. In the real service the second pattern throttles at around 1,000 writes per second or 3,000 reads per second for that key.

Simulating a split

When a partition outgrows its limits, DynamoDB divides its hash range. This model splits a range in half and redistributes the keys.

Python Stand-in: splitting a partition's hash range

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

No item is lost or changed, and the application keeps using the same keys. That is what "invisible" splitting means.

Practical rules that follow

  1. Prefer high-cardinality partition keys: user id, order id, device id. Avoid low-cardinality ones (country, status, a date).
  2. Spread writes: if one logical entity is very hot, add a suffix (score#0 to score#9) and combine results on read. The next lesson shows the pattern.
  3. Do not rely on key adjacency. Hashing destroys it, which is intentional.
  4. Keep an eye on item collections if you use local secondary indexes, because of the 10 GB cap.
  5. Prefer on-demand for unknown traffic; DynamoDB pre-warms partitions to match the peak it has seen.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What decides which partition stores an item?

    The partition key is hashed, and the item goes to the partition that owns that slice of the hash range.
  2. 2. Which situation is most likely to cause a hot partition?

    A date as partition key sends all of today's writes to one key and therefore one partition.
  3. 3. What happens when a partition grows beyond its limits?

    DynamoDB splits partitions by hash range and redistributes items without any action from you.
  4. 4. What does adaptive capacity do?

    Adaptive capacity helps with uneven traffic. It does not lift the per-partition ceilings, so a single hot key can still throttle.

Summary

  • DynamoDB hashes the partition key to pick a partition; items with the same key stay together in sort-key order.
  • Partitions hold roughly 10 GB and serve up to about 3,000 reads and 1,000 writes per second.
  • Partitions split automatically as data or traffic grows.
  • A hot key concentrates load on one partition and throttles even a mostly idle table.
  • Key choice, not table size, controls how well load spreads.

Next: Choosing Good Partition Keys