DynamoDB keys: primary keys and how to choose them

A DynamoDB primary key uniquely identifies an item in a table. It is either a partition key alone (a simple primary key) or a partition key plus a sort key (a composite primary key). Secondary indexes provide additional keys for querying the same data, but their key values do not have to be unique.

Different DynamoDB key types

“Secondary key” usually means the key schema of a secondary index, not a second unique identifier on the table. Start by distinguishing the complete primary key from its individual attributes. That distinction determines which values you must send to read, change or delete one item.

DynamoDB simple key

A simple primary key has one attribute. In a Books table keyed by bookId, every item must have a unique bookId. This fits independent objects that your application usually retrieves by ID.

Use GetItem when you know that ID. Contrary to a common misconception, Query also works on a table without a sort key: supply partition-key equality and it returns at most one matching item. Scan is not the only alternative to GetItem.

A simple key does not support a range query on another attribute by itself. To list every book by author, add an index whose partition key is authorId, or choose a base-table composite key that directly supports that collection. Do not routinely scan all books and filter by author to serve that access pattern.

A random ID can distribute writes well, but distribution and query usefulness are separate concerns. If callers know only the author's ID, a random book ID alone does not give them a direct lookup path.

DynamoDB composite key

A composite primary key has a partition key and a sort key. Items may repeat either value individually, but the pair must be unique. An author can have many books, and different authors can use the same sort-key value without a collision.

For example, a table keyed by authorId and bookId can contain:

Query with authorId = AUTHOR#42 returns that author's books, ordered by bookId. GetItem needs both attributes and returns one item. A query can also restrict the sort key using equality, comparisons, an inclusive range or a prefix.

A composite key is useful when records belong to a collection. It also adds obligations: callers must retain both parts for individual writes and deletes, and the sort order must suit the access pattern. See composite primary keys and hierarchical records for modeling examples and sort-key patterns and operators for range queries.

Reading and writing with a composite primary key

This AWS SDK for JavaScript v3 example assumes Books has String keys authorId and bookId. The document client accepts ordinary JavaScript values.

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

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

await db.send(new PutCommand({
  TableName: "Books",
  Item: {
    authorId: "AUTHOR#42",
    bookId: "BOOK#100",
    title: "Designing applications",
  },
  ConditionExpression: "attribute_not_exists(#pk)",
  ExpressionAttributeNames: { "#pk": "authorId" },
}))

const book = await db.send(new GetCommand({
  TableName: "Books",
  Key: { authorId: "AUTHOR#42", bookId: "BOOK#100" },
  ConsistentRead: true,
}))

const firstPage = await db.send(new QueryCommand({
  TableName: "Books",
  KeyConditionExpression: "#pk = :author",
  ExpressionAttributeNames: { "#pk": "authorId" },
  ExpressionAttributeValues: { ":author": "AUTHOR#42" },
}))

console.log(book.Item, firstPage.Items)
import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
import {
  DynamoDBDocumentClient,
  GetCommand,
  PutCommand,
  QueryCommand,
} from "@aws-sdk/lib-dynamodb"

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

await db.send(new PutCommand({
  TableName: "Books",
  Item: {
    authorId: "AUTHOR#42",
    bookId: "BOOK#100",
    title: "Designing applications",
  },
  ConditionExpression: "attribute_not_exists(#pk)",
  ExpressionAttributeNames: { "#pk": "authorId" },
}))

const book = await db.send(new GetCommand({
  TableName: "Books",
  Key: { authorId: "AUTHOR#42", bookId: "BOOK#100" },
  ConsistentRead: true,
}))

const firstPage = await db.send(new QueryCommand({
  TableName: "Books",
  KeyConditionExpression: "#pk = :author",
  ExpressionAttributeNames: { "#pk": "authorId" },
  ExpressionAttributeValues: { ":author": "AUTHOR#42" },
}))

console.log(book.Item, firstPage.Items)

Without the condition, PutItem replaces an existing item with that complete primary key. The condition is evaluated against the target item; it does not forbid other books by the same author. Continue querying with ExclusiveStartKey when a response contains LastEvaluatedKey.

DynamoDB global secondary index (GSI)

A GSI can organize the table by a different partition key and optional sort key. If Books is keyed only by bookId, an author index makes the query “books by this author” efficient without changing the base-table identity.

Read an index using Query or Scan with IndexName. GetItem does not read a GSI or an LSI. To retrieve a complete item after querying a narrowly projected GSI, use the returned base-table key in a separate GetItem request.

DynamoDB propagates changes to GSIs asynchronously, so GSI queries are eventually consistent. Duplicate GSI key values are permitted: an email-address index, for example, does not enforce unique email addresses.

GSIs now also support multi-attribute keys, with up to four partition-key attributes and four sort-key attributes. That feature applies to GSIs; a base-table composite primary key still consists of one partition-key attribute and one sort-key attribute. The GSI guide covers these schemas, sparse indexes and operational costs.

DynamoDB local secondary index (LSI)

An LSI keeps the base table's partition key and supplies another sort key. A table ordered by bookId could offer an LSI ordered by publishedAt, letting you list one author's books chronologically. LSIs support strongly consistent reads when requested.

Choose LSIs at table creation. You cannot add or delete one independently later. A table with LSIs also has a 10 GB item-collection limit per partition-key value, counting the table items and their LSI entries together. This is not a 10 GB limit on the whole table. The GSI versus LSI comparison explains when those constraints are acceptable.

DynamoDB hot key

A hot key receives enough concentrated traffic to strain the partition serving it. A table may have plenty of total capacity while requests to one customer, author or shared counter are throttled. GSIs have their own distribution, so an index on a small set of status values can be hot even when the base table is well distributed.

High cardinality helps, but traffic distribution matters too. A million customer IDs do not prevent one very busy customer from dominating writes. Adaptive capacity helps DynamoDB respond to skew; it does not make an individual hot item unlimited. The partition-key design guide covers cardinality, diagnostics and write sharding, and DynamoDB hot partitions shows how to find and fix one.

Key types, sizes and changes

Key attributes must be top-level scalars of type String, Number or Binary. A Boolean, list, map, set or null cannot be a key. String keys are case-sensitive: BOOK#100 and book#100 are different values, as are attribute names ID and id.

String and Binary partition-key values can be up to 2,048 bytes; sort-key values can be up to 1,024 bytes. Neither can be empty. These are byte limits, not character counts, so multibyte UTF-8 text reaches the limit sooner. These constraints are documented in the AWS key limits.

The table's key schema cannot be changed in place. Changing an item's key value is a different operation: write an item at the new key and delete the old one, using a transaction if the move must be atomic. UpdateItem cannot modify a primary-key attribute. Changing the table's key attribute names or types requires a new table and a migration.

DynamoDB keys best practices

1. Write down the reads first: single-object lookup, related-object collection, date range or alternate lookup.
2. Pick a simple key for independent ID lookups, or a composite key for grouped and ordered records.
3. Estimate traffic per key, including large tenants and seasonal peaks. Check each index separately.
4. Add indexes for specific queries. Indexing every attribute adds storage, write work and operational risk; there is no universal ideal number of GSIs.
5. Choose domain names such as authorId for clarity, or generic pk and sk names when multiple entity types share a table. Generic names do not remove the need for a documented encoding convention.
6. Monitor consumed capacity, latency and throttling in CloudWatch. Use a sort-key condition to narrow reads; a filter applied afterward does not reduce the data already read.