Defining relationships in SDL
GraphQL types can reference other types. When defining your schema, use the
@relation GraphQL schema directive on the fields that reference other types. For example:
Querying Relationship Fields
Relationship fields can be queried as object fields in GraphQL by including the fields in the selection set. For example, here we query genres connected to a movie node:
Relationships with properties
The above example (annotating a field with
@relation) works for simple relationships without properties, but does not allow for modeling relationship properties. Imagine that we have users who can rate movies, and we want to store their rating and timestamp as a property on a relationship connecting the user and movie. We can represent this by promoting the relationship to a type and moving the
@relation directive to annotate this new type:
This approach of an optional relationship type allows for keeping the schema simple when we don't need relationship properties, but having the flexibility of handling relationship properties when we want to model them.
Querying Relationship Types
When queries are generated (through
makeAugmentedSchema) fields referencing a relationship type are replaced with a special payload type that contains the relationship properties and the type reference. For example:
Here we query for a user and their movie ratings, selecting the
created fields from the relationship type, as well as the movie node connected to the relationship.
Field names for related nodes
There are two valid ways to express which fields of a
@relation type refer to its source and target node types. The
Rated relationship type above defines
to fields. Semantically specific names can be provided for the source and target node fields to the
to arguments of the
@relation type directive.
Default relationship name
name argument of the
@relation type directive is not provided, then its default is generated during schema augmentation to be the conversion of the type name to Snake case.
See the generated mutations section for information on the mutations generated for relationship types.