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.
![](https://cdn.holistics.io/docs/studio/studio-overview.png)
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.
![](https://cdn.holistics.io/docs/studio/studio-toggle-modes.png)
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.
![](https://cdn.holistics.io/docs/studio/studio-branches.png)
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.
![](https://cdn.holistics.io/docs/studio/studio-action-button.png)
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:
![](https://cdn.holistics.io/docs/studio/studio-explore-dataset.png)
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.
![](https://cdn.holistics.io/docs/studio/studio-settings.png)
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:
For more details about each operation, please refer to the dedicated docs.
![](https://cdn.holistics.io/docs/studio/studio-source-control.png)
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.
- 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
- 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
![](https://cdn.holistics.io/docs/studio/studio-view-code.png)
![](https://cdn.holistics.io/docs/studio/studio-view-visual.png)
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.