Skip to main content
Version: v3.x beta

Create a Relationship

What's about to happen?

We're going to create a relationship between entities in our supergraph. By doing this we'll unlock the ability to make API queries across linked information even if that information is on different data sources.

Relationships are defined in metadata from an object type, to a model or command.

By defining a Relationship, all models or commands whose output type is the source ObjectType will have a connection to the target model or command.

Steps

Required

Let's say you have an e-commerce system which includes Customers and Orders. Of course, it would be handy to relate these two entities so that for instance when we query orders, we can see which customer made that order. This is simple with Hasura DDN.

For convenience and organization sake we should add this object to our Orders.hml file so that these common objects are located together. We can use the IDE plugin to help us in authoring the Relationship object to enable this.

If we type out the --- object delineation marker below the last object in our Orders.hml file and then start typing Relationsh... the IDE plugin will popup and assist us with scaffolding out some options. Select Relationship (to model) from the list and press enter, the plugin will output an empty object like the one below:

In any HML file, use the Hasura VS Code extension to create this scaffold
---
kind: Relationship
version: v1
definition:
name: relationship_name
sourceType:
target:
model:
name:
relationshipType:
mapping:
- source:
fieldPath:
- fieldName:
target:
modelField:
- fieldName:

Now we can fill out these fields. To enable an Orders to Customers relationship:

  • We know we want the source of the relationship to be an order. This must be the Orders ObjectType.
  • We know we want the target to be a customer. This must be the Customers Model.
  • We know that on the Orders ObjectType there is a customerId field that maps to the id field customerId on the actual customer which we want to use to define the relationship.
  • We know that the relationship will be 1-to-1. As in, an order only has one related customer. So this will be an Object not an Array.
  • We know that when we query this relationship on an order, we want it to be named: "customer".

So, from this we can fill in this object like the following:

For example, in Orders.hml
kind: Relationship
version: v1
definition:
name: customer
sourceType: Orders
target:
model:
name: Customers
subgraph: my_subgraph
relationshipType: Object
mapping:
- source:
fieldPath:
- fieldName: customerId
target:
modelField:
- fieldName: customerId
description: The customer details for an order
Intellisense autocomplete

The Hasura VS Code extension is powerful. At any point in authoring your object you can press ctrl + space to trigger Intellisense and see the available options you have.

Create a new build to test this.

From the root of your project, run:
ddn supergraph build local --output-dir ./engine
Start your engines!

Want to test your supergraph? Don't forget to start your GraphQL engine and connectors using the following command.

From the root of your project, run:
HASURA_DDN_PAT=$(ddn auth print-pat) docker compose -f docker-compose.hasura.yaml watch

If you haven't included your connector(s) in your docker-compose.hasura.yaml, don't forget to start it as well.

What did this do?

From our example, we can now get customer related information when we query our orders. 🎉

Assuming the structure above, we can run the following nested query:
query {
orders {
orderId
orderDate
customer {
customerId
name
email
}
}
}

Also, from enabling this on the Orders ObjectType , any other model or command which returns this ObjectType now has the ability to return related customers.

There are many other configurations of Relationships which you can enable. See the supergraph modeling section for more info.

Next Steps

Check out information on how to mutate your data with Hasura DDN.

Loading...