Relationships

One-to-many and one-to-one

Relationships between models are defined using the @relate directive. The directive's on argument takes an array of objects consisting of a from column and a to column. For a one-to-many or one-to-one relationship, there is a single object with the from identifying the column on this model and the to identifying the column on the related model. Note: regardless of where the foreign key is related, the from always reflects the current model.

type Film @model(table: "film", pk: "film_id") {
id: ID!
title: String!
description: String!
language: Language! @relate(on: [{ from: "language_id", to: "id" }])
# Note: if there is only one "on" object, GraphQL allows you to
# pass in just the object instead of a list:
language: Language! @relate(on: { from: "language_id", to: "id" })
}

Many-to-many

Many-to-many relationships are defined similarly, but also provide a through argument to identify the join or junction table. They also include two "on" objects -- one joining the current model's table to the junction table and one joining the junction table to the related model.

type Film @model(table: "film", pk: "film_id") {
id: ID!
title: String!
description: String!
actors: [Actor!]! @relate(
through: "actor_film",
on: [{ from: "id", to: "film_id" }, { from: "actor_id", to: "id" }]
)
}

Paginated relationships

Instead of just returning a list of the related type, a relationship field may instead return an object that allows us to paginate over and aggregate the related type's values. To indicate that the relationship field is using this pattern, make sure to provide a value for @relate's pagination argument:

type Film @model(table: "film", pk: "film_id") {
id: ID!
title: String!
description: String!
actors: ActorPage @relate(
through: "actor_film",
on: [{ from: "id", to: "film_id" }, { from: "actor_id", to: "id" }]
pagination: OFFSET
)
}

The only possible value for pagination currently supported is OFFSET. For additional details around pagination, see here.