Skip to main content
Version: PromptQL

Work with Multiple Subgraphs

Introduction​

Learn how to manage multiple subgraphs to streamline team ownership, enforce clear data boundaries, and scale your application easily. This tutorial will show you how to structure your project for flexibility and collaboration, ensuring efficient and adaptable application 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 --with-promptql && cd subgraph-example

Step 2. Add a data source and seed data​

In this tutorial, we'll use the PostgreSQL connector and a 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 application as a model.

Step 4. Create a new local build and test the application​

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

From the PromptQL Playground, talk to your data.

E.g.:
Show me all the users in my application.

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
We'll also create a companion subgraph in the cloud project:
ddn project subgraph create billing

This will provision the subgraph as part of the cloud project that was initialized in our first step.

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 the same 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 application​

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

From your Console's Explorer view, you should see separate subgraphs organized under your supergraph.

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 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 ask PromptQL for information about both customers and orders.

E.g.:
Tell me about each customers' order histories.

Step 11. 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.

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.