Relations

Real data links together: a post has an author and comments, an order has line items. A relation tells Pawabase how two tables connect, so your app can ask for both in one request instead of two. Relations don’t create foreign keys or change the table. They describe a link that already exists through an ordinary column (post.author_id) so expand can follow it.

Two kinds

Kind	The link is stored	Reads as	Result
`belongs_to`	On this table: `posts.author_id` holds an author’s id	”A post belongs to an author”	One object (or `null`)
`has_many`	On the other table: `comments.post_id` holds this post’s id	”A post has many comments”	An array

In Studio

Open the table, choose Settings, and find Relations (Include related rows with ?expand=name). Add relation asks for:

Field	Meaning
Name	What you call it in `expand("name")`: `author`, `comments`
Resource	The other table’s resource
Field	For `belongs_to`: the column on this table that holds the other’s id (`author_id`). For `has_many`: the column on the other table that holds this record’s id (`post_id`)
Type	`belongs_to` or `has_many`

Remove relation deletes it. Existing queries that expand it start failing with a 400, so change the app first.

In your app: expand

const { data: posts } = await pawabase.from("posts").expand("author", "comments").order("created_at", "desc");

posts[0].author.name;           // an object
posts[0].comments.length;       // an array

const post = await pawabase.from("posts").get(id, { expand: ["author"] });

posts = pb.from_("posts").expand("author", "comments").order("created_at", "desc").execute().data
posts[0]["author"]["name"]
posts[0]["comments"]

post = pb.from_("posts").get(post_id, expand=["author"])

Asking for a relation the table doesn’t define is a 400 (“posts has no relation ‘x’”).

Access rules still apply

Each related record is read under its own table’s rules and hides its own write-only columns. If you may read a post but not its author’s profile, the author comes back empty (null, or fewer items in a list). Check for that:

const authorName = post.author?.name ?? "Unknown";

This makes relations safe: expanding can never reveal what a direct read would hide. Filter on the column that holds the link, not on the expanded object:

const { data } = await pawabase.from("posts").eq("author_id", authorId).expand("author");
const mine = await pawabase.from("comments").eq("post_id", post.id).order("created_at");

Many-to-many

A tag system (posts have many tags, tags have many posts) uses a join table with two belongs_to links:

Table	Columns	Relations
`posts`	`id`, `title`	`post_tags`: `has_many` on `post_tags.post_id`
`tags`	`id`, `name`
`post_tags`	`id`, `post_id`, `tag_id`	`post`: `belongs_to` via `post_id`; `tag`: `belongs_to` via `tag_id`

Give post_tags a unique index on (post_id, tag_id). Then read a post’s tags through the join table:

const { data: links } = await pawabase.from("post_tags").eq("post_id", post.id).expand("tag");
const tags = links.map((l) => l.tag);

await pawabase.from("post_tags").create({ post_id: post.id, tag_id: tag.id });   // tag a post

links = pb.from_("post_tags").eq("post_id", post["id"]).expand("tag").execute().data
tags = [link["tag"] for link in links]
pb.from_("post_tags").create(post_id=post["id"], tag_id=tag["id"])

The unique index stops the same tag being added twice.

Performance and limits

Related rows are fetched in one extra query per relation, not one per record, so expanding a list of 50 posts costs two queries, not 51.
A has_many with thousands of children makes responses big. Load those separately with a filter and paging instead of expanding.
Don’t expand relations you won’t show.

In Studio: see them

Tools → Topology draws your tables and the relations between them. See Topology.

Read records

Fetch with expand.

Indexes

Index the link column.

Getting started

Define your data

Change safely

Read and write

Protect and shape

Studio tools

Build well

Two kinds

In Studio

In your app: expand

Access rules still apply

Many-to-many

Performance and limits

In Studio: see them

Read records

Indexes

​Two kinds

​In Studio

​In your app: expand

​Access rules still apply

​Filtering by a related record

​Many-to-many

​Performance and limits

​In Studio: see them

Read records

Indexes

Two kinds

In Studio

In your app: expand

Access rules still apply

Filtering by a related record

Many-to-many

Performance and limits

In Studio: see them