Skip to main content

AML Relationship

Knowledge Checkpoint

A grasp of these concepts will help you understand this documentation better:

Relationship Syntax Definition

Relationship syntax defines relationships among related Data models. The relationship can be defined inside a relationship 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 relationship file with the format relationships.aml and reuse it in the dataset. By this way, the relationship could be shared or reused in many datasets.

Relationship defined in relationship file

//Relationship defined in relationship file: relationships.aml

Relationship order_items_products {
type: 'many_to_one'
from: FieldRef {
model: 'ecommerce_order_items'
field: 'category_id'
}
to: FieldRef {
model: 'ecommerce_products'
field: '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: [
relationship(order_items_products,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 relationship 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 :)