Getting Started with As-Code
We think it would be best if you have a clear understanding of these concepts before reading this documentation:
(This feature is currently in active development. Please reach out if you want to become beta tester)
How to enable AML syntax
AML is available by default on Holistics 4.0 only.
If you are on Holistics 3.0 and would like to try this feature out, please submit a request to us at [email protected]
Initialize a development project
By default, we will help you to create a project in Data Modeling. You can create new files under the project for your development process.
For more information about Holistics project, you can refer to How a project works in Holistics.
Connect to Data Warehouse
Database connection is necessary for Holistics to execute the generated query (from your AML project setup) against. As such, your analysts are able to run & validate if their project setup returns expected result and your end-users can get data and build reports from your prepared set of data.
In order to check which database Holistics supports natively and how to connect, you can refer to our document about Connect Database.
Enable Development mode and start working on your project
Each project has two modes (development and production). You need to enable Development Mode to edit and create project files.
For more information about Project Mode, you can refer to Development Mode, Production Mode and Deploy
Develop Data Model
For more information, please refer to Model Syntax doc
A Model object is being defined in a model file. You can first create a model file by adding a new file with the extension .model.aml
(its full form is model_name.model.aml
).
There are two types of model (Table Model and Query Model) and both of them comprise of model_name, model_type (table or query), its description, model's owner, data_source_name
Table Model
- Step 1: Add a model object in the model file and name it (simply type
Model your_model_name { }
) - Step 2: Inside the curly brackets
{ }
, define model's metadata (type, label. description, ...) - Step 3: Specify which dimensions and measures you want to include in the model.
Example:
Model users {
type: 'table'
label: "Users"
description: ""
owner: '[email protected]'
table_name: '"ecommerce"."users"'
data_source_name: 'demodb'
dimension id {
label: 'Id'
type: 'number'
}
dimension first_name {
label: 'First Name'
type: 'text'
}
dimension email {
label: 'Email'
type: 'text'
}
dimension birth_date {
label: 'Birth Date'
type: 'date'
}
}
SQL/Query Model
- Step 1: Import all the files that store the models you want to include in your model's query (simply add
import 'path/to/model_a_file' {model_a}
) - Step 2: Add a model object in the model file and name it (simply type
Model your_model_name { }
)
Then inside the curly brackets { }
of model object
- Step 3: Define model's metadata (type, label. description, ...)
- Step 4: Insert model name which will be then used inside the query (simply add models
models: [model_a, model_b]
) - Step 5: define the query of the model
- Step 6: Specify which dimensions and measures you want to include in the model.
Example:
import '../base-model/cities.model.aml' {cities}
import '../base-model/countries.model.aml' {countries}
Model location {
type: 'query'
label: 'Location'
owner: "[email protected]"
description: ""
data_source_name: 'demodb'
models: [cities, countries]
query: @sql
SELECT {{ #ci.name }} as city_name,
{{ #co.name }} as country_name
FROM {{ #cities as ci }}
LEFT JOIN {{ #countries as co }} ON {{ #co.code }} = {{ #ci.country_code }}
;;
dimension city_name {
label: 'City Name'
type: 'text'
}
dimension country_name {
label: 'Country Name'
type: 'text'
}
}
Develop Dataset
For more information, please refer to Dataset Syntax doc
A dataset object is defined in a dataset file. You can create a dataset file by adding a new file with the extension .dataset.aml
(its full form is dataset_name.dataset.aml
). A dataset component includes its metadata, models used in the dataset, and the relationship among these models.
Steps to create a dataset
- Step 1: Import all the files that store the models you want to include in the dataset (add
import 'path/to/model_a' {model_a}
) - Step 2: Add dataset object in the dataset file and name it (simply type
Dataset dataset_name { }
)
Then inside the curly brackets { }
of dataset object
- Step 3: Define Dataset metadata (label, description, owner)
- Step 4: Specify the database that Holistics will execute the generated query against (
data_source_name: 'your_data_source'
) - Step 5: Include all the models in the dataset
- Step 6: Define the relationship among those models added in step 5.
Example:
import '../models/base-model/users.model.aml' { users }
import '../models/base-model/cities.model.aml' {cities}
import '../models/base-model/countries.model.aml' {countries}
Dataset general_dataset {
label: "General Dataset"
description: "Short Descritpion"
data_source_name: 'demodb'
models: [
users,
cities,
countries
]
relationships: [
// define relationship between users and cities is many to one
rel(rel_expr: users.city_id > cities.id, active: true),
// define relationship between cities and countries is many to one
rel(rel_expr: cities.country_code > countries.code, active: true)
]
}
Deploy to production
In order to publish what you have been preparing to production and let your business users to explore and get insights from your set of data, you need to click Deploy to Production.
- AML 1.0
- AML 2.0
AML 2.0 deprecates the use of index.aml
. For more information, refer to index.aml file.
Extra step for AML 1.0: Do note that before deploying, you need to create a file called index.aml
and include all the links to the datasets that you wish to deploy to production for your Business Users to explore.
In the example above, I want to publish two datasets raw_ecommerce
and general_dataset
and leave other datasets untouched by Business Users in Reporting.
Step 1: Click Deploy to Production
Step 2: Check your Dataset in Reporting
For more information about the deployment process, please refer to Getting your changes from Development to Production