Relationships¶
Relationships define how models connect to each other. They let the AI Analyst answer questions that span multiple business entities, like "Show me customers and their orders" or "Which products have been purchased recently?" Without them, the AI Analyst has to guess how to join tables, which is a major source of errors. A relationship tells it which keys to join on, what kind of relationship exists (one-to-many, many-to-one, etc.) and how to combine the records (inner join, left join, etc.).
Relationships are declared in the semantic layer. AI Analyst does not read them from foreign-key constraints in your warehouse, so you define each one yourself (or have the Steward draft them).
Create a relationship¶
Availability
- Who can do this: members with the Edit capability in the active Workspace.
Relationships are defined from one model to another. You create a relationship on the model it starts from.
- In Studio, open Models and select the model the relationship starts from (for example
orders). - Open the Relationships tab.
- Click New relationship.
- Fill in the fields described below.
- Click Save relationship.
To delete a relationship, select it and click the Remove (trash) icon next to its name, then confirm Remove relationship?.
If the Workspace has no other model yet, you see "Create another model first to relate to it." instead of the form.
Relationship fields¶
Relationship name¶
Required. A name that describes the connection.
Example: to_customer
On a given model, each relationship to the same target model needs a unique name. If you reuse one, you see "This model already has a relationship with that name to the same target".
Target model¶
The other model this one joins to.
Example: customers
From key¶
The key on this model used to join. Enter the name of a dimension on this model, without the model name.
Example: customer_id
This is usually the foreign key in your source table.
To key¶
The matching key on the target model. Enter the name of the matching dimension on the target model, without the model name.
Example: id
This is typically the primary key in the target table.
Type¶
How many rows on each side typically match:
- One-to-one: Each record in this model connects to exactly one record in the target model
- One-to-many: Each record in this model can connect to multiple records in the target model
- Many-to-one: Multiple records in this model connect to one record in the target model
New relationships start as Many-to-one.
Example: One customer can place many orders, so a relationship from customers to orders is One-to-many, and a relationship from orders to customers is Many-to-one.
Many-to-many links
There is no many-to-many type. For many-to-many links (e.g. students and courses), create a junction model (e.g. enrollments) and relate each side to it with Many-to-one relationships from the junction model (enrollments → students and enrollments → courses).
Join¶
How unmatched rows are kept when querying across the relationship:
- Inner: Only include records that have matches in both models
- Left: Include all records from this model, even if no match exists in the target
- Right: Include all records from the target model, even if no match exists in this model
- Full: Include all records from both models, regardless of matches
Default: Left (keeps all rows from this model, even when there is no match). Choose Inner only when unmatched rows should be dropped.
Filters on the target model still apply with an outer join, but they narrow only the target model's rows. A row the filter removes counts as "no match", so the rows of this model are kept. See Pre-defined Filters.
Where a relationship appears¶
A relationship is defined on the model it starts from and appears only on that model's Relationships tab. It does not appear on the target model's tab. To see or edit it, open the model it was created on.
Why the type matters: fan-out¶
The relationship type tells AI Analyst where a join repeats rows. Joining customers to orders repeats each customer once per order, because the link is to-many as seen from customers.
When a query joins on the relationship's keys, AI Analyst refuses SUM, COUNT and AVG on the repeated model's measures, whether written directly or as a saved measure, instead of returning an inflated total. COUNT(DISTINCT ...), MIN and MAX are still allowed. See Measures across joins.
Because this guard depends on the type you choose, a wrong type means a wrong guard: totals may be refused when they are safe, or inflated when they are not. The check applies only to joins made on the relationship's From key and To key, so make sure both keys are dimensions on their models. Joins on other columns are not checked. Check the cardinality in your data before you save.
Relationships and metrics¶
Metrics reuse the relationships you define on models. When you add a join to a Metric, you pick one of the relationships defined on the metric's model; you can't define separate join keys on the metric. If the list is empty, you see "No relationships available on the anchor model." See Metrics.
Common relationship patterns¶
User activity¶
Connect users to their actions:
users→orders(one user places many orders)users→support_tickets(one user creates many support tickets)
Hierarchical data¶
Connect entities to their parents:
organizations→users(one organization has many users)categories→products(one category contains many products)
Transactional data¶
Connect transactions to entities:
orders→customers(many orders belong to one customer)order_items→products(many order items reference one product)