Relationships
Source: docs/guide/03-relationships.md at origin/main (3688d236), synced 2026-11-05. Do not edit this page here; change the source and run yarn sync:semantic.
A relationship is a to-one link from one dataset to another: each row of the first matches at most one row of the second. It is declared inside the dataset it leaves from, and it is what lets a query or a metric reach the other dataset's fields.
# inside the shipments dataset
relationships:
- name: first_carrier
to: carriers
from_columns: [first_carrier_id]
to_columns: [carrier_id]
cardinality: many_to_one
The rules for a link
from_columnsandto_columnspair up by position, andto_columnsmust be the target's primary key or one of its unique keys. That is what makes the link to-one.cardinalityis optional. If given, it must agree with what the keys imply:one_to_onewhen the source columns are a key of the source too,many_to_oneotherwise.- Both datasets must be on the same connection (
CROSS_CONNECTION_RELATIONSHIPotherwise). - A link only goes one way. Declaring
orders → customerslets an order reach its customer, not a customer reach its orders.
Routes
From a dataset, the anchor, a field of another dataset is reachable when a chain of to-one
links leads there, at most eight long. The shorthand dataset.field takes the shortest chain. It
works when exactly one shortest chain exists, and is refused when two or more tie. The layer
never picks one for you, because the answers differ.
shipments ──first_carrier──▶ carriers
──second_carrier─▶ carriers
categories ──parent_category──▶ categories
From a shipment, carriers.carrier_name could mean either carrier, so it is refused with
AMBIGUOUS_REFERENCE, and the error lists the paths you can write instead:
`carriers.carrier_name` is reachable from shipments by 2 routes; write one of: shipments.first_carrier.carrier_name, shipments.second_carrier.carrier_name
A path names every link: anchor.link[.link…].field. It starts with the anchor's name, then
one link per hop, then the field.
shipments.first_carrier.carrier_nameis the first carrier andshipments.second_carrier.carrier_namethe second. Both may sit in one query, side by side.categories.parent_category.category_nameis a category's parent, through a self link.categories.parent_category.parent_category.category_nameis its grandparent.
A link may also be spelled by its key column when exactly one link of that dataset joins on that
one column: shipments.first_carrier_id.carrier_name is the same reference as
shipments.first_carrier.carrier_name. A link's own name always wins over a key column of the
same name.
A path is refused with INVALID_PATH if it does not start at the anchor, hops a to-many link, or
takes more than eight hops. A link name that does not exist is UNKNOWN_RELATIONSHIP, with
suggestions.
A path is what it means
A path along the one shortest route is the same field as its shorthand. Any other route is a
different field: two references to carrier_name through two links are two columns, joined
separately and named separately in the answer.
When a model stores a reference (a metric's operand or filter, a cache dimension), it stores the route. A path keeps its route even if a second link to the same dataset is added later. A shorthand in a stored metric that a new link makes ambiguous keeps working until the metric is next written, and then has to be respelled as one of the paths the error lists. A metric that sync wrote is respelled by the next sync.
Inside a domain
A domain chooses which links it exposes (Domains). Routes run
only over exposed links, so a domain that exposes only first_carrier lets the shorthand
carriers.carrier_name mean that one. A path through a link the domain hides is
FIELD_NOT_REACHABLE, naming the link.