Reading

Bring related rows along

Put a relation's name in select, with the columns you want from it in parentheses.

select=name,owner(name)select=name,steps(*)select=name,owner(name,manager(name))

A to-one relation, like a todo's owner, comes back as an object, or null when there is none. A to-many relation, like a todo's steps or its tags, comes back as an array, empty when there is nothing.

Relations are found from the foreign keys: todos.owner_id gives owner, and a table holding only two keys, like todo_tags, links todos and tags directly. relation(*) takes every visible column.

Embeds nest. By default a request may walk two relations deep; a third level answers too_deep.

Examples

Each todo with its owner (to-one) and its tags (many-to-many).

/todos?select=name,owner(name),tags(name)

Asking the database...

Each user, their todos, and the steps of each todo.

/users?select=name,todos(name,steps(title))

Asking the database...

Walking the other way: a step, its todo, and the todo's owner.

/steps?select=title,todo(name,owner(name))

Asking the database...

A table related to itself: each user's manager, and the users they manage, under the table's own name.

/users?select=name,manager(name),users(name)

Asking the database...

Three relations deep is one too many.

/todos?select=name,owner(name,manager(name,manager(name)))

Asking the database...

Reading

Bring related rows along

Put a relation's name in select, with the columns you want from it in parentheses.

select=name,owner(name)select=name,steps(*)select=name,owner(name,manager(name))

Embeds nest. By default a request may walk two relations deep; a third level answers too_deep.

Examples

Each todo with its owner (to-one) and its tags (many-to-many).

/todos?select=name,owner(name),tags(name)

Asking the database...

Each user, their todos, and the steps of each todo.

/users?select=name,todos(name,steps(title))

Asking the database...

Walking the other way: a step, its todo, and the todo's owner.

/steps?select=title,todo(name,owner(name))

Asking the database...

A table related to itself: each user's manager, and the users they manage, under the table's own name.

/users?select=name,manager(name),users(name)

Asking the database...

Three relations deep is one too many.

/todos?select=name,owner(name,manager(name,manager(name)))

Asking the database...