Skip to main content
Version: PromptQL

Iterate on your Data Model

Introduction​

After first creating your semantic metadata layer to use with PromptQL, you'll often need to iterate on your underlying data models — 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 the distributed query 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-introspect 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

View resources​

You can then view the resources that have been discovered by running:
ddn connector show-resources my_connector

Add 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 "*"

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

Rebuild​

You can then create a new build:
ddn supergraph build local
Build for Hasura Cloud

You can also create a new build 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

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