AML Relationship

Knowledge Checkpoint

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

• Relationship
• Create a 4.0 Relationship

(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 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

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

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:

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

AML 1.0

//Relationship defined in relationship file: relationships.aml
import '../models/base-model/ecommerce_products.model.aml' { ecommerce_products}
import '../models/base-model/ecommerce_order_items.model.aml' { ecommerce_order_items}
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'
  }
}

AML 2.0

//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

AML 1.0

import '../models/base-model/relationships.aml' { order_items_products}
Dataset ecommerce_orders {
  data_source_name: 'demodb'
  models: [
    model__ecommerce_order_items,
    model__ecommerce_products
  ]
  relationships: [
    relationship(order_items_products,true)
  ]
}

AML 2.0

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 name	Description
type	Define relationship type (whether it's many_to_one, one_to_one or one_to_many)
from	Specify the dimension in from parameter
to	Specify the dimension in to parameter

Relationship config

Parameter name	Description
rel	Define relationship that the config will be applied to
active	Determine should the current relationship be active in dataset