AML Module

Introduction

An AML module is a directory containing similar AML objects and functions together. The files can be arbitrarily nested.

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.

An AML module can contain sub-modules, these modules must be placed within  modules directory in the project's root path.

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.

How to create AML modules

All AML modules are defined under the directory modules. For each sub-module, users need to create a new directory under modules/. The name of the module will be the name of the directory.

For example, the ecommerce module will be modules/ecommerce/file.aml

How to use AML modules

Refer to objects in submodules

• Syntax:

<submodule>.<object-name>

• Example:

//AML project
|-- datasets
|    |-- datasets.aml
|-- models
|    |-- base
|    |    |-- customers.model.aml
|-- modules
|    |-- cohort
|    |    |-- package.aml
|    |    |-- cohort.aml
|    |    |-- ...
|    |-- utils
|         |-- ...
|

Dataset can refer to models in the same module or refer to models in the sub-module like this:

// models/base/customers.model.aml:
Model customers {
  ...
}
// modules/cohort/cohort.aml:
Model retetion_table {
  ...
}

// datasets/datasets.aml:
Dataset customer_details_aml {
  label: 'Customer Details (AML ver.)'
  description: ''
  data_source_name: 'bigquerydw'
  models: [
    customers,  // refer to customers model in the same module
    cohort.retention_table // refer to retention_table model in cohort submodule
  ]
  relationships: [
    ...
  ]
  owner: '[email protected]'
}

Import AML modules with the use keyword

• Users can bring module items into the current file’s scope by using the use statement (these items are only visible in the current file only, not in the whole current module)
• Syntax:

use <module-name> { <object-name>(: <alias-name>)? }

• Example:

// AML project
|-- 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 objects in the module utils.region into this file

Object names are unique within the module scope

• An AML module must be explicitly named or named after the contained directory name by default
• The name of an AML object must be unique within a single module, except the objects within its nested 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

Your whole AML project is a root module. Inside modules/ directory, client_1 is a sub-module, and 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.