Relations

Relations describe how your models connect. Zanith uses them to build JOINs automatically — you never write JOIN SQL by hand.

#Why relations matter

Without relations, getting data from two tables means writing manual SQL JOINs or making multiple queries and stitching results together. With relations, you write.with({ author: true }) and Zanith looks up the foreign key, builds the JOIN, and returns typed results — automatically.

Relations also enable multi-hop traversal (Contract → Organization → Owner), many-to-many through junction tables, and automatic nullable propagation for LEFT JOINs.

#Visual overview

Entity relationship diagram — each arrow becomes an automatic JOIN

#belongsTo

The most common relation. Use it when this modelhas a foreign key column that points to another model's primary key.

TSPost belongs to User

8 lines


1// Post has an authorId column → points to User.id
2relations: {
3  author: m.belongsTo(User, {
4    field: 'authorId',      // FK column on THIS model
5    references: 'id',       // PK column on the TARGET model
6    onDelete: 'cascade',    // optional: cascade, set_null, restrict
7  }),
8}

When you query with .with({ author: true }), Zanith generates:

TSgenerated SQL

2 lines


1LEFT JOIN "users" AS "author"
2  ON "posts"."author_id" = "author"."id"

#hasMany

The reverse of belongsTo. Use it when another model has a foreign key pointing to this model. The FK lives on the other side.

TSUser has many Posts

6 lines


1// User doesn't have a FK — Post.authorId points to User
2relations: {
3  posts: m.hasMany(() => Post, {
4    foreignKey: 'authorId',  // FK column on the OTHER model
5  }),
6}

#hasOne

One-to-one relationship. Like hasMany but only one record on the other side. Typically used for profile/settings patterns.

TSUser has one Profile

6 lines


1relations: {
2  profile: m.hasOne(() => Profile, {
3    field: 'id',
4    references: 'userId',
5  }),
6}

#manyToMany

When two models relate through a junction table. Requires a separate model for the junction. Zanith generates two JOINs automatically.

TSPost has many Tags (through PostTag)

23 lines


1// The junction model
2const PostTag = defineModel((m) => ({
3  name: 'PostTag',
4  table: 'post_tags',
5  fields: {
6    ...m.id(),
7    postId: m.uuid().index(),
8    tagId: m.uuid().index(),
9  },
10  relations: {
11    post: m.belongsTo(Post, { field: 'postId', references: 'id' }),
12    tag: m.belongsTo(Tag, { field: 'tagId', references: 'id' }),
13  },
14}));
15 
16// On the Post model:
17relations: {
18  tags: m.manyToMany(Tag, {
19    through: PostTag,      // the junction model
20    fromField: 'postId',   // junction FK → this model
21    toField: 'tagId',      // junction FK → target model
22  }),
23}

When you query .with({ tags: true }), Zanith generates:

TSgenerated SQL

4 lines


1LEFT JOIN "post_tags" AS "tags_junction"
2  ON "posts"."id" = "tags_junction"."postId"
3LEFT JOIN "tags" AS "tags"
4  ON "tags_junction"."tagId" = "tags"."id"

#Relation types summary

Type	FK lives on	When to use	Example
`belongsTo`	This model	This model has the foreign key	Post → User
`hasMany`	Other model	Other model has FK pointing here	User → Posts
`hasOne`	Other model	One-to-one (other side is unique)	User → Profile
`manyToMany`	Junction table	Many-to-many through junction	Post ↔ Tag

#Next steps

Relational Queries — how to use .with() to JOIN related models in queries
Enums — define fixed value sets for fields like status and role