Launched: AML 2.0 - Introduce AML Modules and important AML Syntax changes

Introduce AML 2.0 Module

Modules are the official way to organize an AML project by grouping similar AML objects and functions together.

For example, they could be a set of objects type (models, dataset) or functions (cohort, mrr, recurring, etc) that you can reuse throughout your AML project.

Using modules, you would be able to follow Modular Data Modeling’s best practices. Organizing related concepts together helps create a neat, uniform structure for your projects. They allow for easier code refactoring and future code reuse.

One way to incorporate selected modules into your project is to use the use keyword.

|-- index.aml
|-- modules
|    |-- cohort
|    |   |-- retention_table.aml
|    |   |-- cohort_items.aml
|    |-- utils
|    |   |-- date_time.aml
|    |   |-- modules
|    |   |    |-- region
|    |   |    |    |-- region_items.aml

use cohort { retention_table, cohort_items: items } // alias cohort_items to items
use utils { date_time }

use utils.region // bring all the items in the module utils.region into this file

utils.date_time // or refer to module's item directly

Object names are unique within module scope

In AML 2.0, object names will be unique in module scope. If you are migrating from AML 1.0 and have duplicated object names in the same module, their name would be appended with a number suffix i.e _1, _2.

Import object statements are no longer required

Since object names will be unique across projects, importing the external files is not required.

Adding datasets to index.aml is no longer required

The file index.aml will no longer be necessary since all the datasets defined in the As-code layer will be published to the end-users in Reporting.

You don’t have to remember to add datasets to the file index.aml anymore.


These look like great changes - am I right in understanding that the ‘modules’ name itself doesn’t matter, more the concept of having modules? Or do you have to have a parent folder called modules?

The requirement for unique naming aspect is disappointing for me - we leverage the ability to have same-named models extensively, as we have multiple environments with the same structure which each have their own set of models but with the same name.

Not needing to import models will at least take some of the pain-points away … and possibly leveraging the modules functionality once I’ve tested it and got a better understanding of how this will operate.

What is the rollout plan looking like for this?

Hi @david-ri,

The modules name matters because the directory modules will store all the sub-modules of your aml project. If you want to create sub-module, you need to create the directory modules first and put all of your sub-modules inside. That’s currently our convention.

If that’s the case, you can modularize your client directory inside the modules/.
For example,

|-- models
|    |-- some.model.aml
|-- datasets
|    |-- some.dataset.aml
|-- modules
|    |-- client_1
|    |   |-- models
|    |   |    |-- users.model.aml
|    |   |    |-- orders.model.aml
|    |   |-- datasets
|    |   |    |-- ecommerce.dataset.aml
|    |-- client_2
|    |   |-- models
|    |   |    |-- users.model.aml
|    |   |    |-- orders.model.aml
|    |   |-- datasets
|    |   |    |-- ecommerce.dataset.aml

We will have a public doc to explain this soon but the object’s names are unique in module scope. To briefly explain, your whole AML project is a root module. Inside modules/ directory, client_1 is a sub-module, client_2 is another sub-module with the same hierarchy as client_1 module. The scope of client_1 is different from that of client_2 so that the model name in client_1 could be the same as client_2.

1 Like

Thanks @Khai_To , so within a module, uniqueness is enforced, but outside of a module you can repeat names?
The structure you’ve shown above is pretty much how we have it structured today (but where client_1 and client_2 are parent folders rather than sub-folders within modules folder), so sounds like we should be able to continue without too much re-factoring - awesome!

At the moment, within a dataset if we can end up with circular references by referencing the same model multiple times. Does aliasing them mean this is no longer the case?

For example:
We have a geography table, and we a shipping metrics table. We want to reference the geography table for two different uses; from_shipping and to_shipping. At the moment we need to create two different geography AML models and reference them separately to avoid the circular reference error.
In AML 2.0, if we alias the geography table twice does this get round the error?

Hi @DataGeekDude
For now, the alias is only for displaying purposes, it will not alter the representation of the model itself so you cannot solve the problem of role playing model < Role Playing Models - Feature Suggestions - Holistics Community>

But we’re working on a better mechanism of model alias. I will let you know when there is an update.

Thanks for the clarification

1 Like

We started implementing modules but it seems that business calculations aren’t able to reference fields in models within modules. For example, with a field named total_userdays in a model events with a folder structure of modules > kd > events.model.aml, none of the following works in business calculations:, events.total_userdays.

The first attempt ( is identical to what is pasted when the field is clicked in the left panel. There’s no issue when simply using the field directly in a report.

How can we reference these fields in business calculations?