DynamoDB partition keys

The partition key — also called the hash key — is the primary key attribute DynamoDB uses to decide which physical partition holds an item. It is the single most consequential decision in a DynamoDB table design, because it is fixed at table creation and determines both how evenly load is spread and which queries are cheap.

How it works

DynamoDB applies an internal hash function to the partition key value and uses the result to select a partition. Items with the same partition key value land on the same partition, stored together and, where a sort key exists, ordered by it.

Uniqueness follows from that:

• In a table with only a partition key, every item must have a distinct partition key value.
• In a table with a composite key, the combination of partition key and sort key must be distinct; the same partition key may repeat with different sort keys.

A query that supplies the partition key reads a single partition and is fast and cheap. A query that does not is a scan, and reads the whole table.

Types of primary key

Simple primary key — one attribute. For example UserID in a users table. Suits records looked up individually by identity.

Composite primary key — partition key plus sort key. For example UserID as the partition key and OrderDate as the sort key in an orders table. This allows many items under one partition key and supports range queries on the sort key: all of a user’s orders in a date window, in order, in a single read.

Choosing one

Favour high cardinality. The key needs many distinct values so that hashing spreads items across partitions. A boolean or a status flag with three values produces three hot spots.

Avoid concentrating current traffic. Even a high-cardinality key behaves badly if requests cluster on a few values at a time. Using a date as the partition key for sensor data is the standard example: every reading taken today hits one partition, which throttles at the per-partition ceiling of 1,000 write units per second while the rest of the table idles.

Match the access patterns. Choose the attribute the application already knows when it needs the data. If lookups are always by customer, the customer identifier is the partition key; if they are always by order, it is the order identifier. Designing the key from the queries backwards is the whole method.

Use composite keys for one-to-many relationships. The partition key represents the “one” side and the sort key the “many” — a customer and their orders, a device and its readings, a document and its revisions. Prefixing the sort key by record type (ORDER#2026-03-14, PROFILE) lets one table hold several record types and still be queried precisely.

Time-series data needs a compound approach. Combining a period with an identifier — sensor_id as the partition key with date as the sort key, or a bucketed sensor_id#2026-03 key where a single sensor is very high volume — keeps writes spread while keeping range queries efficient.

Sequential values are fine when access is even. UUIDs and sequential identifiers distribute well provided reads and writes are spread across them rather than concentrated on the newest.

Effect on performance

A well-chosen partition key spreads reads and writes evenly, which prevents hot partitions and the throttling that follows. Adaptive capacity shifts throughput towards busy partitions automatically, in both capacity modes, so moderate imbalance is absorbed by the service — but a single very hot key still meets the per-partition ceiling, and no amount of provisioned capacity moves it.

DynamoDB scales by adding partitions as a table grows in size or throughput. Effective partitioning is what allows added capacity to be used; poor partitioning means most of the added capacity sits on partitions nobody is reading.

Queries that supply the partition key go directly to the relevant partition. Everything else is a scan or requires a secondary index, which is why the key and the query set have to be designed together.