Relations & embeds

Relation dataclass

Relation(
    join: Literal["left", "inner"] = "left",
    fk: str | None = None,
    through: str | None = None,
    filter: dict[str, Any] | None = None,
)

Metadata describing a relation embedded into a SupabaseModel field.

Example

class Pet(SupabaseModel, table="pets"):
    id: UUID
    name: str
    owner: Annotated[Owner, Relation(join="inner", fk="pets_owner_fkey")]
    tags: Annotated[
        list[Tag], Relation(through="pet_tags", filter={"deleted": False})
    ]

Parameters:

Name	Type	Description	Default
join	Literal['left', 'inner']	"left" (default) or "inner" — translates to !inner.	'left'
fk	str | None	Foreign-key constraint name for disambiguation. PostgREST uses alias:target!fk_name(...).	None
through	str | None	Junction-table or FK hint when PostgREST can't auto-resolve the relationship. Same syntax slot as fk.	None
filter	dict[str, Any] | None	Per-relation filter dict (e.g. {"is_deleted": False}). Operator suffixes like views__gte are honored.	None