DynamoDB partition keys: choosing keys that scale

A DynamoDB partition key is the attribute DynamoDB hashes to distribute table data and the value you supply to select a collection with Query. It is the entire primary key on a simple-key table, or one part of the primary key when a sort key is present. A good partition key matches the values your application knows and spreads activity across many key values, including during peak traffic.

What is a partition key in DynamoDB?

Every table requires a partition key. HASH is its name in the API, so “hash key,” “partitioning key” and “partition key” commonly refer to the same role. The attribute's name might be customerId, id or pk; there is no required spelling.

In a table with only customerId as its key, each customer ID identifies one item. In a table with customerId and orderId, a customer ID can repeat across many items, but each customer/order pair must be unique. The composite-key guide explains grouping and individual-item operations.

Do not equate a partition-key value with a dedicated physical partition. DynamoDB manages physical partitions, which can contain multiple key values. On a table without LSIs, it can also split a large or busy item collection across physical partitions. A key remains a logical query boundary regardless of that placement.

GSIs have their own partition-key schemas and distribution. Their key values do not have to be unique, and an ordinary non-primary-key attribute used by a GSI can be updated on the base item. DynamoDB then propagates the change to the index asynchronously. Native multi-attribute GSI partition keys are also supported; the base table still has one partition-key attribute.

Partition key vs sort key vs primary key

The sort-key guide covers comparisons and ordering. Adding a sort key alone does not distribute heavy writes to one logical key: the traffic pattern and DynamoDB's physical partitioning still matter.

Choosing the right partition key

Start with the reads you need to serve. For each, list what the caller knows, how many items it needs and whether it needs a time range or sort order. Then estimate which key values receive the most traffic, not just the average traffic per item.

A key can have high cardinality, meaning many distinct values, and still have skewed traffic. A million tenants do not help if one tenant generates most requests. Conversely, a low-cardinality attribute is not automatically a problem in a small, low-traffic table. The decision depends on the actual workload.

Do not choose a different key for every item solely to maximize cardinality if doing so turns every useful read into a scan. Key design balances distribution with the ability to retrieve a useful collection efficiently.

Naming and key-value conventions

Use domain names such as customerId when they accurately describe every record. Generic pk and sk are useful for tables containing several entity types, for example CUSTOMER#42 and ORDER#100. Neither style is inherently faster.

Document case normalization, delimiters and serialization rules. CUSTOMER#42 and customer#42 are distinct String values. Reusing the same key names and values in a different table is valid because uniqueness is table-scoped.

Key attributes must be top-level String, Number or Binary scalars. String and Binary partition-key values must be between 1 and 2,048 bytes. A date can be encoded as a String or Number; DynamoDB has no native Date key type. Distinct timestamp partition-key values are hashed, so being numerically increasing alone is not a reason they must land together. A date bucket reused by every write is the concentrated-traffic problem to watch.

Hot partitions and capacity

A physical partition is designed for up to 3,000 read units and 1,000 write units per second. These are capacity units, not universal item-per-second limits. A larger item needs more units, and read consistency changes read consumption. Table-level capacity or quotas can constrain requests before those partition limits are reached.

Adaptive capacity operates in both on-demand and provisioned modes. DynamoDB can rebalance and split for heat, but it cannot make a single frequently updated item unlimited. A continuously increasing sort key beneath one busy partition-key value can also concentrate new writes at the hot end of the collection. Increasing total table capacity alone may not solve either case.

LSIs affect this design: a table with an LSI cannot split one item collection across partitions, and that collection has a 10 GB limit counting table data and LSI entries. Avoid promising an unbounded tenant collection if the table has an LSI. These distinctions are covered in the AWS partition design guidance.

Diagnose the actual throttled resource

1. Inspect ThrottlingReasons on the exception and the associated resource ARN. Distinguish the table from a GSI.
2. Look for TableWriteKeyRangeThroughputExceeded, IndexWriteKeyRangeThroughputExceeded or the corresponding read reason. Capacity and configured maximum-throughput errors require different remedies.
3. Check CloudWatch key-range throttling metrics and Contributor Insights to identify concentrated keys. Its throttled-keys mode records keys when throttling occurs.
4. Check whether the table adapts and the throttling subsides. For an expected sudden increase, assess warm throughput and pre-warming.
5. If concentration persists, change the access pattern, cache appropriate reads or shard writes. Retrying indefinitely does not fix a permanently hot key.

The hot partitions guide works through these steps, and the DynamoDB throttling guide covers the broader diagnosis. A GSI with poor distribution can throttle base-table writes, so repeat this analysis for each affected index.

Write sharding: random or calculated suffixes

Sharding divides one logical workload into several partition-key values. A busy daily event collection might become DAY#2026-10-23#SHARD#00 through DAY#2026-10-23#SHARD#15. Sixteen is an example choice, not an AWS recommendation; choose a shard count from measured rates, item sizes and acceptable read fan-out.

Random suffixes spread writes, but you must retain the chosen shard to retrieve one item efficiently. Generating a new random suffix on every retry can also create duplicates if identity depends on that suffix.

Calculated suffixes derive a shard from a stable identifier. Writers and readers can independently compute the destination. This example uses the same event ID for every retry:

import { createHash } from "node:crypto"

const shardCount = 16

function eventKey(day, eventId) {
  const hash = createHash("sha256").update(eventId).digest().readUInt32BE(0)
  const shard = String(hash % shardCount).padStart(2, "0")
  return {
    pk: `DAY#${day}#SHARD#${shard}`,
    sk: `EVENT#${eventId}`,
  }
}

console.log(eventKey("2026-10-23", "event-100"))
import { createHash } from "node:crypto"

const shardCount = 16

function eventKey(day, eventId) {
  const hash = createHash("sha256").update(eventId).digest().readUInt32BE(0)
  const shard = String(hash % shardCount).padStart(2, "0")
  return {
    pk: `DAY#${day}#SHARD#${shard}`,
    sk: `EVENT#${eventId}`,
  }
}

console.log(eventKey("2026-10-23", "event-100"))

The suffix expands the key space; it does not reserve a physical partition per shard. Reading the full day requires querying every shard, paginating each independently, and merging results if a global order is needed. Bound the query concurrency to control request bursts. The event-ID sort key above does not imply chronological order.

Changing shardCount changes where existing IDs map. Keep the routing scheme stable for a bucket, or version it and teach readers about old and new layouts. Time buckets bound collection size but do not necessarily spread current writes; combine bucketing and sharding when both are needed. AWS describes the core tradeoffs in its write-sharding guide.

Query all items with a partition key

This SDK v3 example assumes myTable has String keys pk and sk. It reads every page for one logical collection:

import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb"

const db = DynamoDBDocumentClient.from(new DynamoDBClient({}))
let cursor

do {
  const page = await db.send(new QueryCommand({
    TableName: "myTable",
    KeyConditionExpression: "#pk = :pk",
    ExpressionAttributeNames: { "#pk": "pk" },
    ExpressionAttributeValues: { ":pk": "CUSTOMER#42" },
    ExclusiveStartKey: cursor,
  }))
  console.log(page.Items ?? [])
  cursor = page.LastEvaluatedKey
} while (cursor)
import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb"

const db = DynamoDBDocumentClient.from(new DynamoDBClient({}))
let cursor

do {
  const page = await db.send(new QueryCommand({
    TableName: "myTable",
    KeyConditionExpression: "#pk = :pk",
    ExpressionAttributeNames: { "#pk": "pk" },
    ExpressionAttributeValues: { ":pk": "CUSTOMER#42" },
    ExclusiveStartKey: cursor,
  }))
  console.log(page.Items ?? [])
  cursor = page.LastEvaluatedKey
} while (cursor)

A table with only pk also supports that query, but it returns at most one matching item. GetItem is normally clearer for a known unique key. You cannot use a prefix or inequality on the partition key in Query; use another key design for that requirement.

Get, delete and update by partition key

For the following examples, Customers is a separate simple-key table whose only primary-key attribute is the String pk. If your table also has a sort key, include it in every Key object.

import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
import {
  DynamoDBDocumentClient,
  GetCommand,
  UpdateCommand,
  DeleteCommand,
} from "@aws-sdk/lib-dynamodb"

const db = DynamoDBDocumentClient.from(new DynamoDBClient({}))
const key = { pk: "CUSTOMER#42" }

const result = await db.send(new GetCommand({
  TableName: "Customers",
  Key: key,
  ConsistentRead: true,
}))
console.log(result.Item)

await db.send(new UpdateCommand({
  TableName: "Customers",
  Key: key,
  UpdateExpression: "SET #email = :email",
  ConditionExpression: "attribute_exists(#pk)",
  ExpressionAttributeNames: { "#email": "email", "#pk": "pk" },
  ExpressionAttributeValues: { ":email": "test@example.com" },
}))

// Run only when you intend to remove this customer item.
await db.send(new DeleteCommand({
  TableName: "Customers",
  Key: key,
}))
import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
import {
  DynamoDBDocumentClient,
  GetCommand,
  UpdateCommand,
  DeleteCommand,
} from "@aws-sdk/lib-dynamodb"

const db = DynamoDBDocumentClient.from(new DynamoDBClient({}))
const key = { pk: "CUSTOMER#42" }

const result = await db.send(new GetCommand({
  TableName: "Customers",
  Key: key,
  ConsistentRead: true,
}))
console.log(result.Item)

await db.send(new UpdateCommand({
  TableName: "Customers",
  Key: key,
  UpdateExpression: "SET #email = :email",
  ConditionExpression: "attribute_exists(#pk)",
  ExpressionAttributeNames: { "#email": "email", "#pk": "pk" },
  ExpressionAttributeValues: { ":email": "test@example.com" },
}))

// Run only when you intend to remove this customer item.
await db.send(new DeleteCommand({
  TableName: "Customers",
  Key: key,
}))

The update changes email, not the partition key. The condition requires the item to exist. The delete removes one customer item; it cannot remove an entire composite-key collection by omitting its sort key.

Can you change a partition key?

The table's partition-key name and type cannot be changed in place. Create a new table and migrate for a different primary-key schema. To move one item to another key value, put it under the new full key and delete the old one, using an appropriate transaction and conditions if the move must be atomic.

A GSI key attribute that is not part of the table primary key can be changed with UpdateItem on the base item. That updates index membership asynchronously; it does not change the GSI's schema. The GSI guide covers alternate-key design and updates.

Before migration, map every read and write to its old and new keys, including retries, duplicate prevention and collection reads. Dynobase data modeling can help document access patterns before application code depends on the new scheme.