Iterate on your Data Model

Introduction

After you've created a DDN supergraph to use with PromptQL, you'll often need to iterate on your data model — whether you're adding a new table, refining a command, or evolving your business logic.

This guide explains when and why you need to run ddn supergraph build local to ensure your changes are reflected in your API.

As a general rule:

• If your metadata changes (like models, commands, or relationships): ✅ rebuild.
• If your connector signature changes (like a function’s arguments or return type): ✅ rebuild.
• If you're only changing implementation logic inside a lambda connector (like editing function body): ❌ no rebuild required.

When to rebuild your application

You add a new source

Each time you add a new data source, you're generating new metadata. This is a good rule of thumb: when metadata changes, a rebuild is required.

After following the steps in the doc referenced above, introspect your source and add your metadata objects before rebuilding.

You edit metadata

Whether your metadata changes are generated via the CLI or you've hand-authored a change (using the VS Code extension), you'll need to create a new build of your application. This will ensure the JSON configuration files consumed by your Hasura Engine are updated with the latest changes.

You make changes to your underlying data model

Depending on your data source, you may be adding a column to a table in PostgreSQL, or a creating a new collection in MongoDB. You may have written new custom logic in TypeScript or want to import a new command from the Stripe connector. Whatever it is, you will follow the same steps each time anything changes in your data source schema to iterate on your data model.

Re-introspecting your data model

Re-introspecting your data model will update the connector configuration to reflect the changes in your data sources.

ddn connector introspect my_connector

Viewing resources

You can then view the resources that have been discovered by running:

ddn connector show-resources my_connector

Adding resources

And add precisely the resources you need running any of the following commands with real values:

ddn model add my_connector my_model
ddn command add my_connector my_command
ddn relationship add my_connector my_relationship

Or if you want to add all resources:

ddn model add my_connector "*"
ddn command add my_connector "*"
ddn relationship add my_connector "*"

Adding semantic Information

It's highly recommended to provide extra natural language descriptions of the resources in your project so that the PromptQL can better understand your data and create appropriate query plans.

The description field can be added to Model, Command and Relationship metadata elements to provide semantic context. See more about semantic information here.

Building a new supergraph

You can then build a new local supergraph by running:

ddn supergraph build local

Build for Hasura Cloud

You can also build a new supergraph for a project on Hasura Cloud:

If you don't have a project on Hasura Cloud, you can create one by running:

ddn project init

Then:

ddn supergraph build create

Restarting services locally

If you are iterating locally, you then need to restart the Docker services by running:

ddn run docker-start

When is rebuilding not necessary?

In short: any time you make modifications that don't require metadata updates. Notably, if you're quickly iterating on the logic of lambda connectors, you can enable Compose Watch to reflect your changes instantly and rebuild your lambda connector's container.