Relationships

Introduction

A relationship allows you to query nested or linked information. This allows you to extend type objects with related models or related commands.

Relationships can take one of two forms:

Type of relationship	Description
Model-to-model	A relationship between two models, allowing you to query related data from one model to another.
Model-to-command	A relationship between a model and a command, allowing you to query related data from a command.

The former is the most common relationship type, allowing you to query related data from one model to another. This enables you to create nested queries, allowing you to fetch related data in a single query.

The latter is a more advanced relationship type, allowing you to query related data from a command. This is useful when you want to query data from a command that is not directly related to a model and even return the data in a nested format. You can imagine enriching or transforming data from a command and returning it as part of a nested query, thereby saving the need for multiple queries or data transformations in your application.

For example, let's say you have a user type in your graph, and also a command which responds with the current logged-in user information (say getLoggedInUserInfo). Now you can link these two, by defining a relationship from the user type to getLoggedInUserInfo.

Let's say we name the relationship currentSession. Now you can make a single query from your client to get a user's data and their current session information.

Example: fetch a list of users and the current session information of each user:

LSP-assisted authoring

Relationships are written in your various HML files. If you're using a compatible editor (such as VS Code with the Hasura extension), LSP-assisted authoring will help you create relationships more efficiently. LSP will provide you with auto-completion, syntax highlighting, and error checking as you write your relationships.

The CLI also works to automatically track your relationships for you whenever you add or update a data connector.

Metadata structure

Relationship

Definition of a relationship on an OpenDD type which allows it to be extended with related models or commands.

Key	Value	Required	Description
kind	Relationship	true
version	v1	true
definition	RelationshipV1	true	Definition of a relationship on an OpenDD type which allows it to be extended with related models or commands.

RelationshipV1

Definition of a relationship on an OpenDD type which allows it to be extended with related models or commands.

Key	Value	Required	Description
name	RelationshipName	true	The name of the relationship.
source	CustomTypeName	true	The source type of the relationship.
target	RelationshipTarget	true	The target of the relationship.
mapping	[RelationshipMapping]	true	The mapping configuration of source to target for the relationship.
description	string / null	false	The description of the relationship. Gets added to the description of the relationship in the graphql schema.
deprecated	Deprecated / null	false	Whether this relationship is deprecated. If set, the deprecation status is added to the relationship field's graphql schema.

Example:

name: Articles
source: author
target:
  model:
    name: Articles
    subgraph: null
    relationshipType: Array
mapping:
  - source:
      fieldPath:
        - fieldName: author_id
    target:
      modelField:
        - fieldName: author_id
description: Articles written by an author

Deprecated

OpenDd configuration to indicate whether an object type field, relationship, model root field or command root field is deprecated.

Key	Value	Required	Description
reason	string / null	false	The reason for deprecation.

RelationshipMapping

Definition of a how a particular field in the source maps to a target field or argument.

Key	Value	Required	Description
source	RelationshipMappingSource	true	The source configuration for this relationship mapping.
target	RelationshipMappingTarget	true	The target configuration for this relationship mapping.

Example:

source:
  fieldPath:
    - fieldName: author_id
target:
  modelField:
    - fieldName: author_id

RelationshipMappingTarget

The target configuration for a relationship mapping.

Must have exactly one of the following fields:

Key	Value	Required	Description
argument	ArgumentMappingTarget	false
modelField	[RelationshipSourceFieldAccess]	false

ArgumentMappingTarget

Key	Value	Required	Description
argumentName	ArgumentName	true

ArgumentName

Value: string

RelationshipMappingSource

The source configuration for a relationship mapping.

Must have exactly one of the following fields:

Key	Value	Required	Description
value	ValueExpression	false	An expression which evaluates to a value that can be used in permissions.
fieldPath	[RelationshipSourceFieldAccess]	false

RelationshipSourceFieldAccess

Key	Value	Required	Description
fieldName	FieldName	true

FieldName

The name of a field in a user-defined object type.

Value: string

ValueExpression

An expression which evaluates to a value that can be used in permissions.

Must have exactly one of the following fields:

Key	Value	Required	Description
literal		false
sessionVariable	string	false

RelationshipTarget

The target for a relationship.

Must have exactly one of the following fields:

Key	Value	Required	Description
model	ModelRelationshipTarget	false	The target model for a relationship.
command	CommandRelationshipTarget	false	The target command for a relationship.

Example:

model:
  name: Articles
  subgraph: null
  relationshipType: Array

CommandRelationshipTarget

The target command for a relationship.

Key	Value	Required	Description
name	CommandName	true	The name of the command.
subgraph	string / null	false	The subgraph of the target command. Defaults to the current subgraph.

CommandName

The name of a command.

Value: string

ModelRelationshipTarget

The target model for a relationship.

Key	Value	Required	Description
name	ModelName	true	The name of the data model.
subgraph	string / null	false	The subgraph of the target model. Defaults to the current subgraph.
relationshipType	RelationshipType	true	Type of the relationship - object or array.

RelationshipType

Type of the relationship.

One of the following values:

Value	Description
Object	Select one related object from the target.
Array	Select multiple related objects from the target.

ModelName

The name of data model.

Value: string

CustomTypeName

The name of a user-defined type.

Value: string

RelationshipName

The name of the GraphQL relationship field.

Value: string