Developing with AML Studio

Introduction

While business users will spend most of their time with dashboards and datasets, data asset builders (like data analysts, analytics engineers...) will spend a large portion of their time in the AML Studio to develop models, datasets and dashboards.

In this document, we will walk you through the components of the AML Studio.

AML Studio Components

When you clicked on the Modeling button on the header, you will be navigated to the AML Studio. This is where you will work with the files in your analytics code base.

Production & Development Modes

On the top of the screen you will see the toggle between Production and Development modes. Production view is a read-only mode which shows the currently deployed analytics code, and the Development mode allows you to modify the code in different development branches.

For more information, please refer to the dedicated Development & Production modes document.

Current working branch

Right next to the Production - Development toggle is the working branch selector. From here you will know which branch of the code you are on, and you can also create new branches.

For more information, please refer to the dedicated Branch Management document.

Code action button

On the top right of the screen is a button to perform actions on your code base. Depending on the context, the button will serve a different function.

For example:

Button	Context
Inactive	When you have just created a new development from the master branch, the button is inactive. The message "Up-to-date with production" is displayed.
Pull from production	When you switch to a development that is out-dated comparing to master branch.
Commit and resolve conflict	When you pull code from master into your current branch, and there are code conflicts.
Commit changes and Push	When you have made changes to the current branch.
Deploy to production	When you have committed all changes.

Project Explore

When you first click on the Modeling button on the header, you are greeted with the Project Explore screen

Two main panels of this screen are the navigation tree on the left, and the file content viewer on the right. Depending on which file type you clicked on, the content viewer will have a different view. For example, this is the screen when you are viewing a Dataset file:

Project Settings

Project Settings is the next item on the leftmost bar of your workspace.

Project Settings screen is where you manage high level settings for your AML Project. For now, the only setting is to link/unlink your current AML Project with an external Git provider, like GitHub or GitLab. For more details, please refer to the dedicated External Git document.

Source Control

Source Control is the final item on the leftmost bar of your workspace.

The Source Control screen is where you perform high-level operations with your code base, for example:

• Version Restore
• Review and discard changes
• Delete branches

For more details about each operation, please refer to the dedicated docs.

Working with files in AML Studio

File names

Files in AML studio can have arbitrary name. For example, all of the following file names are valid:

orders_master.model.aml
orders master.model.aml
[email protected]

However, it is good practice to follow a simple file name convention. Normally we recommend using snake_case for all file names.

Allowed characters in file name

• Any Unicode characters except: NUL, \, /, :, *, ?, ", <, >, |
• No space character at the start or the end of the name
• No period (.) at the end of the name

Object names

In contrast to file names, names of objects like models, datasets... have a stricter constraint. For example:

• Object names must not start with numbers or special characters (except underscore)
• Object names must not contain spaces or special characters

All of the following object names are valid:

// Models
order_master
OrderMaster
_order_master

// Datasets
business_metrics
BusinessMetrics
_business_metrics

However, we recommend using snake_case for all object names.

File names vs. object names

tip

• File names and model/dataset names does not need to match, but it is recommended to do so.
• Changing model/dataset names after having used them in downstream objects will result in breakage.
• You can freely change file names without worrying about breakage, as long as the names of contained object is not changed.

In AML Studio, file names and the names of the contained model/dataset do not need to match. A typical usage of this feature is to have two (or several) different folders containing similar models & datasets files:

// Note that all models and dataset names still need to be unique in the project

data_warehouse
    ├── region_asia
    │   ├── orders.model.aml                // contains model orders_asia
    │   ├── products.model.aml              // contains model products_asia
    │   └── business_metrics.dataset.aml    // contains dataset business_metrics_asia
    |
    └── region_europe
        ├── orders.model.aml                // contains model orders_europe
        ├── products.model.aml              // contains model products_europe
        └── business_metrics.dataset.aml    // contains model business_metrics_europe

To effectively implement this structure, you will need a convention and have a strong adherence to said convention. For most organizations, simply making files unique with prefixes and suffixes will be enough.

Supported files

Since Holistics follows the "Infrastructure as Code" paradigm, objects like models, datasets, dashboards... can be defined in plain text files with .<feature>.aml extensions. Below is the list of files currently supported in Holistics's AML Studio.

File name	Corresponding Feature
model_name.model.aml	Data Model
dataset_name.dataset.aml	Dataset
dashboard_name.page.aml	Canvas Dashboard
relationships.aml	Model Relationships
schedules.aml	Query Model Persistence Scheduling
file_name.md	Markdown contents, like README.md. Basic Markdown syntax are supported.

You can create files of arbitrary extension in AML studio, but only files with these extensions have meanings to Holistics, and their contents are rendered correctly in the UI.

For more details about each feature, please refer to the dedicated document.

File content viewer

In general, the file content viewer has two modes: Visual mode and Code mode.

• The Code mode displays file contents in plain text, and you will configure models, datasets, reports... using purely code.
• The Visual mode, on the other hand, displays a graphical representation of the file content, and allows some simple interactions with the objects.

Code mode

Visual mode

Depending on the file type, the Code and Visual modes behave differently. For more details, please check the dedicated document of each feature specified in the Supported Files section.

File organization

For more details about how to organize files, please refer to the Set up a Holistics Project document.