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

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.

An example relationship for a users table to a sessions table:

kind: Relationship
version: v1
definition:
  name: user
  description: |
    Associates a session with the user who initiated it. This relationship connects each record in the 
    `sessions` model to a corresponding entry in the `users` model using the `userId` field. It's typically 
    used to fetch user details—such as name, email, or role—when querying session data.
  sourceType: sessions
  target:
    model:
      name: users
      subgraph: operations
      relationshipType: Object
  mapping:
    - source:
        fieldPath:
          - fieldName: userId
      target:
        modelField:
          - fieldName: id

Lifecycle

Create a relationship

To add a relationship you will need to have a data connector which has already introspected the data source. Follow the relevant tutorial in How to Build with PromptQL to get to that point.

Add your relationship by passing the connector's and relationship's names:

# Alternatively, you can add all relationships: ddn relationship add <connector_link_name> "*"

ddn relationship add <connector_link_name> <relationship_name>

Not sure which relationships you have?

Relationships are generally available for any foreign-key values defined in your data source. You can see a list of all available resources using the CLI:

ddn connector show-resources <connector_name>

For each relationship, you'll find a metadata object added in the relevant parent model's HML file.

You can now create a build, serve it, and begin having meaningful conversations with the related data through PromptQL. With explicitly defined relationships in place, PromptQL can create dynamic query plans that accurately address your requests and provide deep insights into and across your data.

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.

Re-introspect your source:

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

Next steps

• If you're comfortable with relationships, check out permissions next to get a better idea of how to restrict access and manipulation of connected data.
• You can learn more about relationships in the metadata reference docs.