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

• The DDN CLI, VS Code extension, and Docker installed
• A new or existing supergraph
• A new or existing subgraph
• Existing models or commands in your supergraph which can be related to an ObjectType. For more information on creating a model in your supergraph you can see the sections on adding data source entities to the API for your data source. And for commands you can see the integrating business logic section.

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 \
  --subgraph-env-file my_subgraph:my_subgraph/.env.my_subgraph.local

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 up --build --watch

If you haven't included your connector(s) in your compose.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.