Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 37 ยท Data Modeling Patterns

Relationships With Adjacency Lists

Model one-to-one, one-to-many and many-to-many relationships in DynamoDB with embedding, shared partition keys, the adjacency list pattern and an inverted index.

Real data is connected: customers have orders, students attend courses, users follow users. A relational database stores each connection with foreign keys and rebuilds it with joins. DynamoDB has no joins, so you decide at write time how each relationship is stored. There are four main techniques, and which one you pick depends on how big the relationship is and how you read it.

This lesson goes from the simplest case to many-to-many, using the same stand-in store each time. Remember that the store is a Python teaching toy, not the DynamoDB service.

One-to-one and small one-to-many: embed

If the child data is small, always read with the parent, and does not grow without limit, put it inside the item as an attribute: a map for one-to-one, a list for a few children.

JSON
{
  "PK": "USER#u1", "SK": "PROFILE",
  "name": "Ana",
  "address": { "city": "Lisbon", "zip": "1000-001" },
  "phones": ["+351 900 000 001", "+351 900 000 002"]
}

Embedding costs nothing extra to read and updates atomically with the parent. Do not embed when the list can grow (comments, orders) because an item cannot exceed 400 KB, and rewriting a large list on each change wastes write capacity.

One-to-many at scale: shared partition key

For unbounded children, give each child its own item and let it share the parent's partition key, with a sort key that groups and orders the children:

PK SK
CUSTOMER#c1 PROFILE
CUSTOMER#c1 ORDER#2026-03-01#o17
CUSTOMER#c1 ORDER#2026-03-09#o21

A Query with begins_with(SK, "ORDER#") returns the orders in date order, and you can page through them or take the newest 10 with Limit=10 and ScanIndexForward=false. One caution: a single partition key should not grow without bound if it also receives heavy traffic; see hot partitions.

If children need a lookup by their own ID without the parent, add a GSI keyed on the child's ID, or a small lookup item.

Many-to-many: the adjacency list

Students take many courses and courses have many students. The adjacency list pattern stores one item per edge of the relationship. The edge item's partition key is one side, its sort key the other:

PK SK Meaning
STUDENT#s1 COURSE#c10 s1 is enrolled in c10
STUDENT#s1 COURSE#c11 s1 is enrolled in c11
STUDENT#s2 COURSE#c10 s2 is enrolled in c10

"Which courses does s1 take?" is Query PK = STUDENT#s1, begins_with(COURSE#). For the other direction, "who takes c10?", you need the edges under the course. Create a GSI whose keys are the table's keys swapped (the inverted index): GSI1PK = SK and GSI1SK = PK. Then Query GSI1PK = COURSE#c10 lists the students. Both directions use only keys.

Four ways to store a relationship

Embed Small, read together
Shared PK Unbounded children
Edge items Many-to-many
Inverted GSI Read the other direction

Choose by size and read direction.

1 / 2

Try it: enroll students and read both directions

Python Adjacency list with an inverted index

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.

Notice that the edge is one item. Dropping a course needs one delete, and the inverted view updates because the index is derived from the same data. If you need extra attributes on the relationship (enrollment date, grade, role), put them on the edge item.

Hierarchies and fetching a parent with children

A hierarchy such as folders and files can be stored with the path in the sort key. A sort key like FOLDER#root#docs#2026 lets begins_with(SK, "FOLDER#root#docs") return a whole subtree. Alternatively store one item per node with parentId and read level by level with one query per level (use it for shallow trees).

For "the order and its lines" use the shared partition key from the previous lesson (single-table design). For "the post and its newest 20 comments", use the post's PK with COMMENT#<timestamp> sort keys and read backwards.

Denormalizing and keeping copies in sync

You often copy a small piece of the parent into the child, such as the customer name in each order, so that listing orders needs no second lookup. The price is that a name change leaves stale copies. Decide per field: copy values that are historically true (the price at order time, the shipping address) and that you never update; keep a reference for values that must be current and read them in a second request (BatchGetItem) or maintain the copies from a stream.

Python Embed or separate 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.

Embedding a list that grows will eventually fail with a validation error. Separate items never hit that wall.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. When should a one-to-many relationship be embedded in the parent item?

    Embedding is free to read and atomic to update, but items are capped at 400 KB and a growing list rewrites the whole item.
  2. 2. How is a many-to-many relationship usually stored?

    The adjacency list pattern stores each relationship as its own item, so it can be added or removed independently and carry attributes.
  3. 3. How do you query the relationship in the opposite direction?

    An index whose partition key is the base table's sort key (and vice versa) lets you read the edges from the other side.
  4. 4. Why are values like the product price at order time often copied into the order?

    The price at purchase should not change when the catalog price does, and copying it removes the need for a join.

Summary

  • Embed small, bounded children; use separate items under a shared partition key for unbounded ones.
  • Many-to-many relationships become edge items; an inverted GSI reads them backwards.
  • Edge items can carry their own attributes such as enrollment date.
  • Copy values that are historically true; reference values that must stay current.
  • Watch the 400 KB item limit when embedding.

Next: Hot Partitions and Write Sharding