Work with Multiple Subgraphs

Introduction

Learn how to manage multiple subgraphs in Hasura DDN to streamline team ownership, enforce clear data boundaries, and scale your API easily. This tutorial will show you how to structure your project for flexibility and collaboration, ensuring efficient and adaptable API development.

In this tutorial, you'll learn how to:

• How to organize your project into subgraphs
• How to create a subgraph as part of your local project
• How to create relationships across subgraphs
• How to create a subgraph on a cloud project

We'll demonstrate this by creating a supergraph with two subgraphs: one owned by a customers team and another owned by the billing team.

This tutorial should take less than twenty minutes.

Setup

Step 1. Initialize a new local project

Create the project directory and move into it:

ddn supergraph init subgraph-example && cd subgraph-example

Step 2. Add a data source and seed data

In this tutorial, we'll use the PostgreSQL connector and our sample PostgreSQL database:

postgresql://read_only_user:[email protected]:5432/v3-docs-sample-app

In your project directory, run the following, choose hasura/postrges, and pass the connection URI above when prompted:

ddn connector init customers_pg -i

Step 3. Generate the Hasura metadata

Next, use the CLI to introspect your PostgreSQL database:

ddn connector introspect customers_pg

After running this, you should see a representation of your database's schema in the app/connector/customers_pg/configuration.json file; you can view this using cat or open the file in your editor.

Now, track the table from your PostgreSQL database as a model in your DDN metadata:

ddn models add customers_pg users

Open the app/metadata directory and you'll find a newly-generated file: Users.hml. The DDN CLI will use this Hasura Metadata Language file to represent the users table from PostgreSQL in your API as a model.

Step 4. Create a new local build and test the API

To create a local build, run:

ddn supergraph build local

The build is stored as a set of JSON files in engine/build.

Start your local Hasura DDN Engine and PostgreSQL connector:

ddn run docker-start

Your terminal will be taken over by logs for the different services.

In a new terminal tab, open your local console:

ddn console --local

In the GraphiQL explorer of the console, write this query:

query GET_USERS {
  users {
    id
    name
  }
}

You'll get the following response:

{
  "data": {
    "users": [
      {
        "id": "7cf0a66c-65b7-11ed-b904-fb49f034fbbb",
        "name": "Sean"
      },
      {
        "id": "82001336-65b7-11ed-b905-7fa26a16d198",
        "name": "Rob"
      },
      {
        "id": "86d5fba0-65b7-11ed-b906-afb985970e2e",
        "name": "Marion"
      },
      {
        "id": "8dea1160-65b7-11ed-b907-e3c5123cb650",
        "name": "Sandeep"
      },
      {
        "id": "9bd9d300-65b7-11ed-b908-571fef22d2ba",
        "name": "Abby"
      }
    ]
  }
}

Add a subgraph

Step 5. Create a new billing subgraph

Use the DDN CLI to create the subgraph in your local metadata:

ddn subgraph init billing --graphql-type-name-prefix billing

You'll see a new billing directory added to your local project. The CLI pre-configured this with all the necessary files and subdirectories to contain data connectors and their metadata.

Additionally, by adding the --graphql-type-name-prefix flag, we're ensuring any types generated by the CLI will not conflict with existing types from our other subgraph. If we had concerns about conflicts of root-level GraphQL fields, we could also add the flag --graphql-root-field-prefix.

Then, add it to your supergraph.yaml config:

ddn subgraph add billing --subgraph ./billing/subgraph.yaml --target-supergraph ./supergraph.yaml

You can verify this by opening the supergraph.yaml in the root of your project. You should see the following:

kind: Supergraph
version: v2
definition:
  subgraphs:
    - globals/subgraph.yaml
    - app/subgraph.yaml
    - billing/subgraph.yaml

Step 6. Switch contexts

Switch contexts to the billing subgraph:

ddn context set subgraph billing/subgraph.yaml

This will simplify our subsequent CLI commands as the CLI will now know that — whenever the --subgraph flag is required — we're referencing the billing subgraph.

Step 7. Add a data source and seed data

As before, we'll use the PostgreSQL connector with our sample database:

postgresql://read_only_user:[email protected]:5432/v3-docs-sample-app

In your project directory, run:

ddn connector init billing_pg -i

Notice where this connector was added

Since you created the billing subgraph and switched contexts in Step 6, the CLI added the connector in the billing subgraph directory.

Step 8. Generate the Hasura metadata

Next, use the CLI to introspect the PostgreSQL database:

ddn connector introspect billing_pg

After running this, you should see a representation of the database's schema in the billing/connector/billing_pg/configuration.json file; you can view this using cat or open the file in your editor.

Now, track the table from your PostgreSQL database as a model in your DDN metadata:

ddn models add billing_pg orders

Open the billing/metadata directory and you'll find a newly-generated file: PaymentInformation.hml. The DDN CLI will use this Hasura Metadata Language file to represent the payment_information table from PostgreSQL in your API as a model.

Step 9. Create a new local build and test the API

To create a local build, run:

ddn supergraph build local

Kill your local services from their terminal tab:

CTRL+C

Restart your local Hasura DDN Engine and PostgreSQL connector:

ddn run docker-start

In a new terminal tab, open your local console:

ddn console --local

You should see both root-level fields for users and orders in your GraphQL API. Additionally, if you navigate to the Explorer tab in the left-hand navigation, you should see your supergraph's data domains organized into two separate subgraphs.

Step 10. Create a relationship across subgraphs

As our models are in different subgraphs, we'll need to explicitly define a relationship between these using Hasura metadata.

Add the following to your Users.hml file:

---
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

By calling out the billing subgraph in the relationship object, the Hasura VS Code extension can help you with validating your configuration.

Then, create a new build:

ddn supergraph build local

And kill your services with CTRL+C before restarting them:

ddn run docker-start

You can now query across subgraphs:

query GET_USERS_AND_ORDERS {
  users {
    id
    name
    orders {
      id
      createdAt
      status
    }
  }
}

And get a response like:

{
  "data": {
    "users": [
      {
        "id": "7cf0a66c-65b7-11ed-b904-fb49f034fbbb",
        "name": "Sean",
        "orders": [
          {
            "id": "7ff13435-b590-4d6b-957f-f7fd39d4528a",
            "createdAt": "2023-10-29T17:02:50.958076+00:00",
            "status": "complete"
          }
        ]
      },
      {
        "id": "82001336-65b7-11ed-b905-7fa26a16d198",
        "name": "Rob",
        "orders": [
          {
            "id": "9891596a-a732-4c1c-902c-1a112da48fec",
            "createdAt": "2023-10-29T17:02:51.150084+00:00",
            "status": "complete"
          }
        ]
      },
      {
        "id": "86d5fba0-65b7-11ed-b906-afb985970e2e",
        "name": "Marion",
        "orders": [
          {
            "id": "85581445-752a-4aef-9684-b648eb5d5f42",
            "createdAt": "2023-10-29T17:02:51.085229+00:00",
            "status": "complete"
          }
        ]
      },
      {
        "id": "8dea1160-65b7-11ed-b907-e3c5123cb650",
        "name": "Sandeep",
        "orders": [
          {
            "id": "c7406b75-6b24-41e4-9c5b-ff3feada9447",
            "createdAt": "2023-10-29T17:02:50.889261+00:00",
            "status": "processing"
          }
        ]
      },
      {
        "id": "9bd9d300-65b7-11ed-b908-571fef22d2ba",
        "name": "Abby",
        "orders": [
          {
            "id": "98612470-1feb-4b91-88f7-9289d652ee87",
            "createdAt": "2023-10-29T17:02:51.021317+00:00",
            "status": "complete"
          }
        ]
      }
    ]
  }
}

Step 11. Create a cloud project

Using your default context, create a new cloud project:

ddn project init

Your .hasura/context.yaml will be updated to reflect the new project name. The default context of this project is now linked to the cloud project you just created.

Additionally, the CLI will output information about each subgraph that it generated in your cloud project, including billing.

Step 12. Create a new build on your production project

Finally, create a new build on your cloud project:

ddn supergraph build create

The CLI will return a console URL which you can navigate to; within the Explorer tab, you'll find your project's subgraphs, including billing.

Adding subgraphs after project initialization

When you initialize a cloud project, the subgraphs in your local metadata will automatically be generated in your cloud project. If you add subgraphs after initialization, you'll have to manually add the subgraphs to the cloud project as well. Learn more here.

Next steps

In the example above, you learned the steps to organize your project into multiple subgraphs for clearer ownership between teams. To take this a step further, many teams prefer to implement multi-repository setups wherein a single subgraph can be added to an existing or private team repository. Learn more here.