Intermediate8 min read

How DynamoDB Partition Keys Work

Your is an address: it tells DynamoDB where an item lives, not how to sort it.

How do DynamoDB partition keys work?

DynamoDB runs your through an internal hash function, and the output decides which physical partition stores the item. The key is not sorted or indexed like a SQL column.

Pick a high-cardinality key and load spreads across many partitions; pick a low-cardinality one and a few partitions take all the traffic.

  • The key is hashed, not sorted. Two keys that look alike get unrelated hashes, so similar keys don't end up near each other.
  • A partition is a storage unit with limits. Each one caps out around 10 GB, 3,000 read units/sec and 1,000 write units/sec, so your throughput depends on how many partitions your keys spread across.
  • Hot keys are the footgun. Funnel most requests at one partition-key value and you throttle on that partition while the rest of the table sits idle.
  • High-cardinality keys win. The more distinct, evenly hit key values you have, the more partitions absorb the load.

Start with what the key does

Coming from SQL, a primary key is a sorted, indexed column you JOIN and ORDER BY on. In DynamoDB the partition key (sometimes called the hash key) does something different: it decides placement.

Its hash maps to a keyspace, and the keyspace is sliced into ranges, each range owned by a physical partition: an allocation of storage, replicated across Availability Zones.

So the partition key answers one question: which partition holds this item? The , if you have one, orders items inside the partition.

Once a large or busy item collection splits, the sort key also decides which of the resulting partitions an item lands on.

(The 2022 USENIX ATC paper: "The output from the hash function and the sort key value (if present) determines where the item will be stored.")

Follow one write through the hash

Say you run a SaaS that ingests device readings. Your table SensorReadings uses a partition key deviceId and a sort key readingTs. You write a reading for deviceId = "vac-7741". The write takes this path from your key to its partition:

keyspace slicePutItemdeviceId = 'vac-7741'Hash thepartition keyHash maps to apoint in the keyspaceWhich rangeowns it?Partition P2Item stored,ordered by readingTs

The write for vac-7741 is hashed to a point in the keyspace, that point falls in P2's range, and the item lands on P2, ordered there by readingTs.

"vac-7741" and "vac-7742" differ by one character, but their hashes are unrelated, so where they land doesn't depend on how alike they look.

On a table with many partitions they will usually land on different ones; on a small table they may share one.

The 2007 Amazon Dynamo paper also hashed keys across nodes, on a consistent-hashing ring.

DynamoDB kept the hashing and replaced the ring: per the 2022 USENIX ATC paper, each partition owns "a disjoint and contiguous part of the table's key-range". From the Dynamo paper to DynamoDB has the rest.

Paste a list of partition-key values below to see how a hash scatters them across buckets. A high-cardinality set spreads evenly; reuse one value and it all piles into a single bucket, the the next section is about.

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 internal hash. The actual function, keyspace, and partition boundaries are AWS internals.

Use it to build a feel for spread vs skew, not to predict which physical partition a key lands on.

Respect the partition's hard limits

A physical partition is finite: about 10 GB of storage, 3,000 read units/s and 1,000 write units/s (AWS partition key design for throughput; Constraints for "10GB is the maximum size of a partition").

DynamoDB adds partitions on its own as they fill and as they run hot, and when you raise provisioned throughput.

A split can carve one partition key's item collection at a sort-key boundary, so a busy key's load can spread over more partitions.

Splitting can't rescue a single hot item, an ever-increasing sort key, or a table with an LSI. Physical partitions covers the limits and the splits in full.

Name the trap: the hot partition

A hot partition is the classic footgun. It happens when one partition-key value (or a tiny set of them) absorbs a disproportionate share of traffic.

Concrete failure: you switch SensorReadings to a partition key region with values like "us-east" and "eu-west". Three regions means three item collections, and each starts on one partition.

Slam "us-east" with reads and that partition throttles at 3,000 read units/s while the table's total capacity sits unused.

A split for heat can spread a collection, but not when the traffic hits one item or walks readingTs in order, which is how telemetry is written and read.

Adaptive capacity can shift unused throughput toward a busy partition and may isolate one hot item onto its own partition, but never above that partition's limits.

Each case that splitting can't rescue has its own way out:

  • One hot item, read-heavy: put DAX in front of it, if your reads can be eventually consistent.
  • One hot item, write-heavy (a counter), or an ever-increasing sort key: shard the partition key with a suffix so writes land on several collections.
  • An LSI pinning the collection: model the alternate sort order as a GSI instead. LSIs exist only from CreateTable, so that means a new table and a data move.

Choose a high-cardinality key

The fix is cardinality: the number of distinct key values, and how evenly traffic hits them.

  • Low cardinality (region, status, true/false): few partitions, traffic concentrates, you throttle early.
  • High cardinality (deviceId, userId, a ticket ID): many values hashing across many partitions, load spreads, headroom grows.

Coming from SQL you'd happily index a status column and filter on it. As a DynamoDB partition key that's a trap, because it can't spread.

Keep low-cardinality attributes as filters or as a secondary index's sort key, never as the thing that decides placement.

When a good key still skews (a handful of whale tenants outpacing the rest), add a suffix such as tenantId#3 to spread one logical value over several keys. Hot partitions covers random vs calculated suffixes and reading the shards back.

To target items within a partition once your key is spread, you'll write a KeyConditionExpression on the sort key. You can assemble one against your own schema in the DynamoDB expression builder before wiring it into code:

deviceId = "vac-7741" AND begins_with(readingTs, "2026-06")

That reads one device's June readings, every timestamp on June 30 included, as a Query, not a Scan.

A BETWEEN "2026-06-01" AND "2026-06-30" would stop at the bare string "2026-06-30" and miss every reading timestamped later that day.

The partition key picks the item collection; the sort-key condition narrows the items.

Pitfalls and next steps

  • Don't pick a key by what reads well in SQL. Pick it by what spreads. Cardinality first, query convenience second.
  • Don't assume the table's total capacity is yours per key. Throughput is per partition; one hot value can throttle while the table looks idle. To see which key, turn on CloudWatch Contributor Insights (its throttled-keys mode is cheap to leave on).
  • Don't count on a split to fix a hot key. Splits are automatic and follow observed traffic, but they can't spread one item or a monotonic sort key. Give the table enough distinct keys to spread across.

Once your key spreads cleanly, the next decisions are how to lay out items inside a partition (see single-table design) and when a secondary index is the right tool for a second access pattern.

Download DynoTable and run a GROUP BY over your partition key in the SQL Workbench to see which keys hold the most items. That shows collection size, which the 10 GB LSI cap watches; traffic per key comes from Contributor Insights.

By Dmitriy · Updated