Skip to main content

Relationship

Knowledge Checkpoint

We think it would be best if you have a clear understanding of these concepts before reading this documentation:

(This feature is currently in active development. Please reach out if you want to become beta tester)

Relationship Syntax Definition

Relationship syntax defines relationships among related Data models. The relationship can be defined inside a model file or directly inside the dataset file.

To define relationship, you need to specify:

  • Relationship type: many_to_one | one_to_one
  • The dimension used as join field between two related models

For the relationship to be functional in the dataset, you need to also specify the configuration of the relationship (active status)

Defining the relationship inside the dataset file

To understand the relationship that is being defined, consider this example:

Full-form

You can chose to use full-form to create a relationship:

Dataset ecommerce_test {
label: 'Ecommerce Test'
data_source_name: 'demodb'
models: [
ecommerce_cities,
ecommerce_countries
]
relationships: [
RelationshipConfig {
rel: Relationship {
type: 'many_to_one'
from: ref('ecommerce_cities','country_code')
to: ref('ecommerce_countries','code')
}
active: true
}
]
}

  • Relationship {} is used to define a relationship between two model fields using model name and field name, which is equivalent to this

relationship

  • RelationshipConfig {} is a function used to define the configuration of the relationship in a dataset, which is equivalent to this

relationship config

 RelationshipConfig {
rel: rel
active: true|false
}

In that, rel: declares relationships we could have in the dataset, active is the status of each relationship in the dataset. The active:true means that the defined relationship is enabled in the data set ecommerce_test

  • The output will be:

relationship n-1

Short-form

Or you can use a short-form version:

Dataset ecommerce_test {
label: 'Ecommerce Test'
data_source_name: 'demodb'
models: [
ecommerce_cities,
ecommerce_countries
]
relationships: [
relationship(ecommerce_cities.country_code > ecommerce_countries.code, true)
]
}

Using this approach, you can just conveniently include the relationships’ logic directly in the dataset file. This will make the dataset file easier to read in-line.

Defining Reusable Relationship

Defining relationships directly in the dataset has a drawback: reusability. The result is only for that specific dataset (ad-hoc relationship).

Another way is to define the relationship in the model file and reuse it in the dataset. By this way, the relationship could be shared or reused in many datasets.

Relationship defined in model file

//Relationship defined in model file: ecommerce_order_items.model.aml

Model ecommerce_order_items{....}
Relationship rel_category {
type: 'many_to_one'
from: ref('ecommerce_order_items','category_id')
to: ref('ecommerce_products','category_code')
}

Import relationship from model file to dataset file

Dataset ecommerce_orders {
data_source_name: 'demodb'
models: [
model__ecommerce_order_items,
model__ecommerce_products
]
relationships: [
RelationshipConfig {
rel: rel_category
active: true
}
]
}
Note

Holistics adds a tooltip in code mode when hovering to the relationship object in the dataset file to show its definition without having to open the model file to look up it.

Parameter Definition

Relationship

Parameter nameDescription
typeDefine relationship type (whether it's many_to_one, one_to_one or one_to_many)
fromSpecify the dimension in from parameter
toSpecify the dimension in to parameter

Relationship config

Parameter nameDescription
relDefine relationship that the config will be applied to
activeDetermine should the current relationship be active in dataset

Let us know what you think about this document :)