Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 37 ยท Data Model and Keys

Primary Keys: Partition Key and Sort Key

Understand simple and composite primary keys in DynamoDB, how the partition key and sort key work together, and how keys decide which queries are possible.

The primary key is the most important decision you make when designing a DynamoDB table. It does three jobs at once: it identifies each item uniquely, it decides where the item is stored, and it defines which lookups are cheap. You cannot change a table's primary key after creation, so it pays to understand the two forms it can take.

Simple primary key: partition key only

A simple key has one attribute, the partition key (also called the hash key). Each item has a unique partition key value. GetItem needs that value, and the item comes straight back.

Use a simple key when every access is "give me the thing with this id": user profiles by UserId, sessions by SessionId, products by Sku.

Composite primary key: partition key plus sort key

A composite key has two attributes: the partition key and the sort key (also called the range key). The pair must be unique, but many items can share one partition key as long as their sort keys differ.

TEXT
PK = CUSTOMER#amina    SK = PROFILE
PK = CUSTOMER#amina    SK = ORDER#2026-03-01#5001
PK = CUSTOMER#amina    SK = ORDER#2026-03-14#5002
PK = CUSTOMER#ben      SK = PROFILE

Items with the same partition key form an item collection. They are stored together and sorted by the sort key. That one fact gives you powerful queries:

  • all items in a collection (one customer's profile and orders),
  • items whose sort key starts with a prefix (ORDER#),
  • items in a sort-key range (orders in March),
  • the newest or oldest N items (sorted ascending or descending, with a limit).

What you cannot do is range over partition keys. To Query, the partition key must be an exact match. There is no "all customers whose id starts with a".

flowchart LR
    subgraph P1["Partition key: CUSTOMER#amina"]
    A1["SK: PROFILE"] --> A2["SK: ORDER#2026-03-01#5001"] --> A3["SK: ORDER#2026-03-14#5002"]
    end
    subgraph P2["Partition key: CUSTOMER#ben"]
    B1["SK: PROFILE"]
    end

Items sharing a partition key are neighbors, ordered by sort key.

How lookups depend on the key

Operation What it needs
GetItem The full primary key (partition key and sort key if the table has one)
PutItem The full primary key inside the item
UpdateItem, DeleteItem The full primary key
Query An exact partition key, plus an optional condition on the sort key
Scan Nothing, but it reads the entire table

If a table has a sort key and you supply only the partition key to GetItem, the request is rejected. Supplying only the partition key is what Query is for.

A model of composite-key behavior

The stand-in below implements the rules above: uniqueness of the pair, full key for get, and a query by partition key with an optional sort-key prefix. It is a teaching model, not the real service.

Python Stand-in: a composite-key table with Query

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.

The last line is the "latest order" query: sort descending, take one. In real DynamoDB it is ScanIndexForward=false with Limit=1.

Uniqueness is part of the design

Because PutItem overwrites an item with the same key, the key also controls what counts as a duplicate. If two different things can legitimately produce the same key, one will silently replace the other.

Python Stand-in: same key means same item

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.

The real API lets you prevent the silent replacement with a condition expression (attribute_not_exists(PK)), which a later lesson on conditional writes covers.

Declaring a composite key

Terminal
aws dynamodb create-table \
  --table-name AppData \
  --attribute-definitions \
      AttributeName=PK,AttributeType=S \
      AttributeName=SK,AttributeType=S \
  --key-schema \
      AttributeName=PK,KeyType=HASH \
      AttributeName=SK,KeyType=RANGE \
  --billing-mode PAY_PER_REQUEST

HASH is the partition key, RANGE is the sort key. Generic names such as PK and SK are common in multi-entity tables because the same attribute holds different kinds of values.

Guidance for choosing

  • Partition key: pick a value with many distinct values that your requests spread evenly across. The next lessons expand on this.
  • Sort key: pick the attribute you want to order and range over inside a partition: a timestamp, a version number, an entity type prefix.
  • Compose values with a stable delimiter (#) and keep zero-padded numbers or ISO dates so text order matches logical order.
  • Think about reads first. The key must let your most important queries use GetItem or Query.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What must be unique in a table with a composite primary key?

    Many items may share a partition key, but the pair of partition key and sort key identifies exactly one item.
  2. 2. Which request is invalid on a table that has both a partition key and a sort key?

    GetItem requires the full primary key. To read by partition key alone, use Query.
  3. 3. How are items with the same partition key stored?

    An item collection is stored together and sorted by sort key, which is what makes range queries cheap.
  4. 4. Can a Query use a range of partition key values, such as ids beginning with a?

    Query requires equality on the partition key. Ranges are only available on the sort key.

Summary

  • A primary key is either a partition key alone or a partition key plus sort key.
  • The key identifies the item, decides its storage location and defines the cheap access paths.
  • Items sharing a partition key form a collection, sorted by sort key.
  • GetItem needs the full key; Query needs an exact partition key and optionally a sort-key condition.
  • The primary key cannot be changed after the table is created.

Next: How DynamoDB Partitions Your Data