Skip to main content

Relationships

Synced from semantic-layer

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
  • from_columns and to_columns pair up by position, and to_columns must be the target's primary key or one of its unique keys. That is what makes the link to-one.
  • cardinality is optional. If given, it must agree with what the keys imply: one_to_one when the source columns are a key of the source too, many_to_one otherwise.
  • Both datasets must be on the same connection (CROSS_CONNECTION_RELATIONSHIP otherwise).
  • A link only goes one way. Declaring orders → customers lets 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_name is the first carrier and shipments.second_carrier.carrier_name the second. Both may sit in one query, side by side.
  • categories.parent_category.category_name is a category's parent, through a self link. categories.parent_category.parent_category.category_name is 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.