Cross-repo Relationships

Connecting across subgraphs with relationships

When you have multiple subgraphs, either in a single-repo or multi-repo setup, you can query across linked information. This is done by creating a Relationship object in metadata which defines how fields from one type map to a model or command.

Single-repo relationships

In a single-repo setup, relationships are straightforward to manage. All subgraphs are in the same repository and the Hasura VS Code extension can be used to assist with authoring relationships, providing auto-complete and validation.

Cross-repo relationships

Advanced plan

You will need a project on the DDN Advanced plan to use multi-repo federation and cross-repo relationships.

In a multi-repo setup, subgraphs that contain objects you want to relate can reside in different repositories, some of which you may not have access to. In these cases the Hasura VS Code extension cannot validate the entirety of the Relationship object and you will manually author cross-repo relationships and ensure that the field mappings are correct. However, upon creating a supergraph build, all cross-subgraph metadata is validated to prevent mistakes from being deployed to the final API.

You can still easily use the Hasura DDN console to explore the supergraph and test relationships across subgraphs once you have created a build.

If you perform a local supergraph build using the CLI (ie. ddn supergraph build local), cross-repo relationships will be ignored and will not be validated. If you run the build locally you will only see the subgraphs in that repository, and any relationships to subgraphs from other repositories will be missing.

Example

Let's say you have a supergraph with two subgraphs, each managed in different repositories: users and products.

The users subgraph in repo 'A' has a User type with a field called user_favorite_product_id.

The products subgraph in repo 'B' has a Product type with a field called id.

To create a relationship between these two types in different repositories, you would create a Relationship object in the users subgraph metadata as normal.

The LSP is able to understand that the Product type is in a different subgraph to which it does not have access and will not give a warning on the foreign type.

kind: Relationship
version: v1
definition:
  name: favorite_product
  sourceType: User
  target:
    model:
      name: Product
      subgraph: products
      relationshipType: Object
  mapping:
    - source:
        fieldPath:
          - fieldName: user_favorite_product_id
      target:
        modelField:
          - fieldName: id

This Relationship object defines a relationship called favorite_product from the User type to the Product type. The mapping field specifies how the user_favorite_product_id field in the User type maps to the id field in the Product type.

After defining the cross-repo relationship, it's important to note that you won't be able to test this locally. To see the relationship in action, you'll need to follow these steps:

1. Create a new supergraph build on DDN using the ddn supergraph build create command. (Subgraph builds do not get an API, so supergraph builds are required to test.)
2. You can then use the Hasura DDN console to explore and test the relationship across subgraphs.
3. If you have admin permissions, you can apply the subgraph to the supergraph with the ddn subgraph apply command.

Remember, cross-repo relationships only come into effect when the subgraphs are combined in the DDN environment. Local development and testing are limited to the scope of your current repository.

With this relationship defined, you can now query the favorite_product field on the User type to retrieve the related Product.

query {
  users {
    id
    name
    favorite_product {
      id
      name
    }
  }
}

For more information on how to create Relationships check out this page.