AML Relationship

Knowledge Checkpoint

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

• Relationship
• Create a 4.0 Relationship

Relationship Syntax Definition

In AML, you can define relationships between related data models in two ways: directly inside your dataset file for quick, one-off connections, or in a separate relationship file when you want to reuse the same relationship across multiple datasets.

Every relationship needs a few key pieces of information:

• Relationship type: many_to_one or one_to_one
• Join fields: The dimensions you're connecting between the two models
• Active status: Whether the relationship should be enabled in your dataset

Defining Relationships Inside the Dataset File

When you define relationships directly in your dataset file, you have two syntax options: full-form and short-form. Let's look at both using an example that connects cities to their countries.

Full-form Syntax

The full-form syntax gives you explicit control over each part of the relationship. Here's how it looks:

ecommerce_test.dataset.aml

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

Let's break down what each part does:

The Relationship {} block defines how two models connect to each other. It specifies which fields link together (in this case, country_code from cities to code in countries):

The RelationshipConfig {} wrapper controls the relationship's behavior within your dataset. Think of it as the "on/off switch" and other settings for the relationship:

RelationshipConfig {
  rel: Relationship {}    // Which relationship to configure
  active: true|false      // Should it be enabled?
}

When you set active: true, you're telling Holistics to enable this relationship in the ecommerce_test dataset. Here's what the final result looks like in the UI:

Short-form Syntax

If you prefer a more compact approach, you can use the short-form syntax:

ecommerce_test.dataset.aml

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)
  ]
}

The short-form syntax uses operators to specify the relationship type:

• > for many-to-one relationships (e.g., many cities belong to one country)
• - for one-to-one relationships (e.g., one user has one profile)

The second parameter (true or false) sets whether the relationship is active. This compact syntax accomplishes the same thing as the full-form example above, just with less typing.

Defining Reusable Relationships

While defining relationships directly in your dataset works great for one-off cases, it has a limitation: you can't reuse that relationship definition in other datasets. If you find yourself connecting the same models across multiple datasets, you'll end up duplicating code.

The solution? Define your relationship once in a separate relationship file, then reference it wherever you need it.

Create a Relationship File

First, create a relationship in a file named relationships.aml:

relationships.aml

Relationship order_items_products {
  type: 'many_to_one'
  from: r(ecommerce_order_items.product_id)
  to: r(ecommerce_products.id)
}

Reference the Relationship in Your Dataset

Now you can use this relationship in any dataset by referencing its name:

ecommerce_orders.dataset.aml

Dataset ecommerce_orders {
  data_source_name: 'demodb'
  models: [
    ecommerce_order_items,
    ecommerce_products
  ]
  relationships: [
    relationship(order_items_products, true)
  ]
}

Note

When you hover over the relationship name in code mode, Holistics shows you a tooltip with the full relationship definition. No need to open the relationship file to look it up.

Parameter Reference

Relationship

Parameter name	Description
type	The relationship type: many_to_one, one_to_one
from	The source dimension (which field you're joining from)
to	The target dimension (which field you're joining to)

Relationship Config

Parameter name	Description
rel	The relationship this configuration applies to
active	Whether this relationship should be active in the dataset (true/false)