Relationships Connect Data

Introduction

Relationships allow you to connect your data, enabling PromptQL to understand the semantic connections between your data entities and accurately talk to all your data. By defining these relationships, PromptQL can generate intelligent query plans that navigate complex data structures to provide meaningful insights.

Examples of how PromptQL uses relationships to deliver powerful insights:

• When asking PromptQL about a customer's purchasing patterns, it can understand the relationship between Customer, their Orders, and each Product item in those orders, delivering comprehensive purchasing analysis. (Model to Model)
• When requesting customer behavior analytics, PromptQL can correlate a Customer with their app usage metrics from another data source, providing cross-data-source insights. (Model to Model in another subgraph or data connector)
• When analyzing international sales performance, PromptQL can combine Order data with live currency conversions from an external API through a lambda data connector, delivering real-time financial analysis. (Model to Command)

Relationships can be added between any kind of semantically related models and/or commands. They do not need to be related in the data source by, for example, a foreign key. They also do not need to be backed by the same data source or be in the same subgraph.

Lifecycle

Many relationships can be created automatically by the DDN CLI from detected underlying connections such as foreign keys. In such cases the lifecycle in creating a relationship in your metadata is as follows:

1. Introspect your data source using the DDN CLI with the relevant data connector to fetch the entity resources.
2. Add the detected relationships to your metadata with the DDN CLI.
3. Create a build of your supergraph API with the DDN CLI.
4. Serve your build to enable PromptQL to access your data with the Hasura engine either locally or in the cloud.
5. Iterate on your PromptQL experience by repeating this process or by editing your metadata manually as needed.

If the relationship cannot be detected automatically, you can easily manually create a relationship in your metadata and then perform lifecycle steps 3-5 from above as needed.

Create a relationship

Relationships are defined in metadata from an object type, to a model or command. But since models and commands are also defined with object types, you can think of relationships as being between models and/or commands.

The target command can be enabled with a custom piece of business logic on a lambda data connector, or a native mutation operation.

Using the DDN CLI

The DDN CLI and your data connectors will detect many relationships in your data sources automatically, for instance from foreign keys in a relational database, and once introspected, you can add them to your metadata.

Introspect your data source:

ddn connector introspect <connector_name>

Show the found relationships:

ddn connector show-resources <connector_name>

Add a relationship to your metadata:

ddn relationship add <connector_link_name> <collection_name>

Or optionally add all relationships found for a connector at once:

ddn relationship add <connector_link_name> "*"

Context for CLI commands

Note that the above CLI commands work without also adding the relevant subgraph to the command with the --subgraph flag because this has been set in the CLI context. You can learn more about creating and switching contexts in the CLI context section.

Manually creating a relationship

Relationships can also be manually added to your metadata.

The VS Code extension can help you to author relationships.

For example, you can configure a relationship so that when a user asks PromptQL about a Customer's purchasing history, it can also access their Orders data.

Create a relationship in your metadata:

---
kind: Relationship
version: v1
definition:
  sourceType: Customers # The existing source object type which also defines the model
  name: orders # A name we want to use when we query the Orders from the Customer
  description: |
    Links customers to their purchase orders.
    One customer can have multiple orders.
    This is a critical business relationship that supports order history lookups, 
    customer purchase analysis, and revenue attribution.
    Historical orders are retained even if customer becomes inactive.
  target:
    model: # The target can be a model or a command
      name: Orders # The existing model that we want to access when we query the Orders from the Customer
      relationshipType: Array # The relationship type which can be Object or Array. Since a customer can have many orders, we use an Array.
  mapping: # The mapping defines which field on the source object type maps to which field on the target model
    - source:
        fieldPath:
          - fieldName: customerId # The existing field on the source object type that we want to map to the target model
      target:
        modelField:
          - fieldName: customerId # The existing field on the target model that we want to map to the source object type

By defining this Relationship object, PromptQL will understand that customers and orders are connected, allowing it to generate accurate query plans that can navigate from customer data to their associated orders when responding to user queries about customer purchasing behavior.

Learn more about the Relationship object.

Update a relationship

Your underlying data source may change over time. You can update your relationship to reflect these changes.

If you have an automatically detected relationship and a property on the source object type has changed, you can update the relationship to reflect this change.

First, update your connector configuration and models.

Update your source introspection:

ddn connector introspect <connector_name>

Then, update your model:

ddn model update <connector_name> <model_name>

Now, you can either delete the existing Relationship object and use the DDN CLI to add it again:

Delete your existing relationship manually and add it again:

ddn relationship add <connector_link_name> <collection_name>

Or you can update the Relationship object manually. Learn more about the Relationship object.

Delete a relationship

If you no longer need a relationship, simply delete the Relationship metadata object manually. It is fully self-contained.

Reference

You can learn more about relationships in the metadata reference docs.