How to Work with Multiple Subgraphs

Introduction

In your daily development, you'll often encounter scenarios where your project requires multiple subgraphs to represent distinct domains. We'll walk you through the best practices for working with multiple subgraphs, setting their context, and establishing relationships across them to create a unified supergraph.

Set subgraph context

If you're working in a project with multiple subgraphs, there will be the need to switch between subgraphs when executing commands with the DDN CLI. While the CLI supports a --subgraph flag, it is much more convenient to set your subgraph in context.

Switch between context using the path to the subgraph's configuration file:

ddn context set subgraph ./<subgraph-name>/subgraph.yaml

You can verify this by checking the current context:

ddn context get subgraph

Which should return the path you entered. This will ensure any commands you run — such as adding a new data connector — are run in the appropriate subgraph.

Create relationships across subgraphs

Within any model's HML file, you can add a relationship object as you normally would but add a subgraph key-value pair identifying in which subgraph the model is located.

---
kind: Relationship
version: v1
definition:
  name: orders
  sourceType: Users
  target:
    model:
      subgraph: billing
      name: Orders
      relationshipType: Array
  mapping:
    - source:
        fieldPath:
          - fieldName: id
      target:
        modelField:
          - fieldName: userId

Considerations for multi-repository projects

Hasura's VS Code extension assists in authoring metadata objects like the one above. It offers autocomplete and knows about your metadata, enabling validation and short feedback loops for you as developer. However, when in a multi-repository project wherein subgraphs are split among various repositories, the extension will only be able to assist with the metadata which is locally available.

For more information, see the next steps section below.

Next steps

• Learn how to split subgraphs across repositories