Retyping Relations

Using [[retype_relation]] to Customize Asset Links

The [[retype_relation]] directive provides fine-grained control over how rescile creates relationships from your asset CSV files. By default, if a column header in one asset file matches the name of another asset file (e.g., a database column in application.csv), a relationship of type database is created.

[[retype_relation]] allows you to override this convention-based behavior in two powerful ways:

1. Rename the relationship type to be more semantically meaningful (e.g., change database to CONNECTS_TO).
2. Remap the target resource type, allowing a column to link to a resource type that doesn’t match its name (e.g., a db_host column can link to a host resource).

This directive is defined within a model file and is scoped to the origin_resource of that file.

How [[retype_relation]] Works

Let’s explore the common patterns for using this directive.

Pattern 1: Renaming the Relationship Type

This is the most common use case: making your graph more readable and expressive.

Goal: An application asset has a database column. By default, this creates a database relationship. We want to rename it to CONNECTS_TO.

Assets: data/assets/application.csv

name,owner,database
billing-api,team-alpha,billing-db

data/assets/database.csv

name,type
billing-db,PostgreSQL

Model (data/models/application.toml):

origin_resource = "application"

[[retype_relation]]
property_key = "database" # The column name in application.csv
new_type = "CONNECTS_TO"   # The new relationship type

Graph Impact: Without the rule, the relationship would be (application) -[database]-> (database). With the rule, it becomes much clearer:

graph TD
    subgraph "Before (Default)"
        A(application: billing-api) -- "database" --> B(database: billing-db)
    end
    subgraph "After (With Rule)"
        C(application: billing-api) -- "CONNECTS_TO" --> D(database: billing-db)
    end

Pattern 2: Remapping the Target Resource Type

This pattern is essential when your CSV column names don’t align with your asset filenames.

Goal: An application asset has a primary_contact column containing the name of a person. The people are defined in person.csv. We need to link the primary_contact column to the person resource type.

Assets: data/assets/application.csv

name,owner,primary_contact
billing-api,team-alpha,jane.doe

data/assets/person.csv

name,email
jane.doe,jane.doe@example.com

Without a rule, rescile would look for a non-existent primary_contact.csv file and fail to create the link.

Model (data/models/application.toml):

origin_resource = "application"

[[retype_relation]]
property_key = "primary_contact" # The column name
target_resource_type = "person"   # Link to a 'person' resource

Graph Impact: The rule tells rescile to use the values from the primary_contact column to look up resources from person.csv. The relationship type defaults to the property_key.

graph TD
    A(application: billing-api) -- "primary_contact" --> B(person: jane.doe)

Pattern 3: Combining Renaming and Remapping

You can use all keys together for maximum flexibility.

Goal: Using the previous example, we want to remap the primary_contact column to the person resource type and rename the relationship to OWNED_BY.

Model (data/models/application.toml):

origin_resource = "application"

[[retype_relation]]
property_key = "primary_contact"
target_resource_type = "person"
new_type = "OWNED_BY"

Graph Impact: This combines both actions, resulting in the most semantically rich graph structure.

graph TD
    A(application: billing-api) -- "OWNED_BY" --> B(person: jane.doe)