Intermediate8 min read

How to Model Data in DynamoDB

In SQL you model entities and relationships first, then trust the query planner to assemble whatever you ask for later. DynamoDB inverts that. You model the reads you already know you'll make, and the keys exist to serve them.

There is no join engine and no planner picking a strategy at runtime. A Query reads one partition along one key, and that is the entire performance contract.

AWS says it plainly in its best-practices guide: "you shouldn't start designing your schema for DynamoDB until you know the questions it will need to answer."

How do you model data in DynamoDB?

List every query the app makes, then design a and so each question resolves to a single Query or GetItem. Co-locate items that are read together, range over values in the sort key, and add a GSI for any access pattern the base table can't serve.

  • The questions are the spec. The nouns are a distraction.
  • Each question must be one Query or GetItem. If a frequent question needs a Scan, the model is wrong.
  • Co-located items share a ; anything you range over goes in the .
  • A frequent question the base table can't answer gets a , not a Scan with a filter.

The primitives you model with

A table has a partition key (PK) that picks which physical partition an item lives on, and an optional sort key (SK) that orders items within that partition.

The AWS core-components docs call the pair the item's primary key. A Query always targets exactly one PK value and can range over or filter the SK. That's the whole toolkit.

Two consequences drive every decision below:

  1. Items that are read together should share a partition key so one Query returns them in a single billed request.
  2. Anything you want to range over (recent matches, top ratings) must live in the sort key, because that's the only attribute Query can order and bound.

When a question needs a different access shape than the base table provides, you add a Global Secondary Index: a re-projection of the table under a different PK/SK.

(For GSI versus Local Secondary Index, see GSI vs LSI.)

Step 1: Frame the problem as questions, not tables

The worked domain is a multiplayer game leaderboard: players, the matches they play, and their per-season ranking. Resist the urge to draw players, matches, and scores tables. Instead write down every read the app performs:

  • Fetch one player's profile by id.
  • List a player's recent matches, newest first.
  • Show the top N players for a given season, ranked by rating.
  • Look up a player by their public handle (e.g. for a profile URL).

Each one must resolve to a single Query (or GetItem), because that's the only access shape DynamoDB serves cheaply at scale.

If a question can only be answered by scanning the table, you'll feel it in latency and cost; see Query vs Scan for why a Scan is the footgun to avoid.

The whole method is a short, ordered pipeline you run once per domain:

NoYesYesNoList the questionsEnumerate access patternsDesign PK / SKto serve themEvery readone Query?Add a GSIper leftover readValidate againstreal dataNew questionappears?Ship the model

Step 2: Design the keys, one question at a time

Use a single table with generic, overloaded key attributes named PK and SK (the single-table approach), because a player and their matches are read together.

Invent your own prefixes; here PLAYER#, MATCH#, and SEASON# tag the entity type inside otherwise-generic keys.

Questions 1 and 2 (profile + recent matches) share a partition, so both hang off the same PK:

PKSKattributes
PLAYER#u8231MATCH#2026-06-23T11:42:07Z#m_51c0result=loss, ratingDelta=-15, mapId
PLAYER#u8231MATCH#2026-06-23T14:05:31Z#m_8f2aresult=win, ratingDelta=+18, mapId
PLAYER#u8231PROFILEhandle, region, createdAt

Query PK = "PLAYER#u8231" returns the profile, every match and (below) the player's season rows in one read. For the profile alone, GetItem.

For recent matches, SK begins_with "MATCH#" with ScanIndexForward = false walks them newest-first. The full ISO-8601 timestamp orders them, and the match id on the end keeps two matches in the same second from overwriting each other.

Questions 3 and 4 can't be answered from that partition: they pivot on season rank and on handle, neither of which is the base PK. Each gets a GSI.

Add two pairs of generic index attributes: seasonPartition / seasonSort for the rank index, and handlePartition / handleSort for the handle index.

The handle keys go on the profile item. The season keys go on one item per player per season, so past leaderboards keep their rows when a new season starts:

PKSKseasonPartitionseasonSorthandlePartitionhandleSort
PLAYER#u8231PROFILE——HANDLE#nighthawkPLAYER#u8231
PLAYER#u8231SEASON#2026-Q2SEASON#2026-Q2RATING#01842——

Now a Query on the season index WHERE seasonPartition = "SEASON#2026-Q2" with ScanIndexForward = false returns players ranked by rating: that's the leaderboard. Add Limit for the top N.

A second index keyed on handlePartition = "HANDLE#…" resolves a public handle to a player id in one read. One physical table, four single-Query access patterns.

A GSI enforces no uniqueness and updates asynchronously, so two players can claim the same handle and a just-claimed handle may not resolve yet.

If handles must be unique, write a HANDLE#nighthawk marker item in the same TransactWriteItems as the profile, guarded by attribute_not_exists; a GetItem on the marker then replaces the handle index. Uniqueness on multiple attributes shows the transaction.

Step 3: Validate the model in DynoTable

Run each query and check that it returns exactly the items you expect and nothing more.

Open the table in DynoTable, run the leaderboard query against the season index, and confirm the partition comes back ranked and bounded: no Scan, no client-side sorting.

Running the season-leaderboard Query against the GSI in DynoTable and inspecting the ranked result.
Running the season-leaderboard Query against the GSI in DynoTable and inspecting the ranked result.

When you build the condition expressions for these queries (the begins_with, the seasonPartition = :p, the placeholder :p binding), let the DynamoDB Expression Builder do it.

It generates the KeyConditionExpression, the ExpressionAttributeNames, and the ExpressionAttributeValues, so a reserved word like result or a typo'd placeholder doesn't fail your read with a ValidationException at run time.

Step 4: Pitfalls and next steps

A few traps to check before you ship the model:

  • Add indexes from the question list, not speculatively. Every GSI adds a write per item it indexes and its own storage, so an unused one is recurring cost.
  • Watch partition heat. Every rating change rewrites that season's index key, so one busy season concentrates writes on one GSI key, capped at about 1,000 write units per second. Shard it as SEASON#2026-Q2#0..N-1, query the top N from each shard and merge client-side; hot partitions covers the sizing.
  • Zero-pad and ISO-8601 everything numeric or temporal in a string sort key, so byte ordering matches the order you mean.
  • A new frequent question = a new key or index, not a Scan. When a new access pattern appears later, extend the keys; don't paper over it with a filter.

For a head start on Step 2, the free Single-Table Design tool turns a list of access patterns like this one into a PK/SK/GSI plan, with example items and cost hints.

For a question you didn't model, DynoTable's SQL Workbench (paid plans) runs GROUP BY and aggregates client-side.

Its JOINs go through a table's partition key (on a table without a sort key) or a GSI partition key. A self-join on this one table works only through a GSI, since the table has a sort key; an unmodeled question here is still a Scan.

Try DynoTable to browse your table, run these queries against the base table and each GSI in separate tabs, and watch the access patterns you designed return exactly what you planned.

By Dmitriy · Updated

Try this design interactively

Sketch your entities and access patterns in the free DynamoDB Single-Table Design tool — it suggests PK/SK key templates, previews the item collections, and shows which patterns need a GSI.

Open the Single-Table Design tool