Skip to main content

How a project works in Holistics

(This feature is currently in active development. Please reach out if you want to become beta tester)

What is a project?

In Holistics, a project is a collection of files that defines all the basic components of Holistics Modeling Layer (data models, datasets, relationships) as well as Holistics Reporting Layer (Dashboard, Visualization). If you are familiar with git, each Holistics project has an associated Git repository and by default, we will manage your project's Git repository for you.

Project files

project-name (root)
|- model-directory
| |- model-file-1.model.aml
| |- model-file-2.model.aml
| |- model-file-n.model.aml
|- dataset-directory
| |- dataset-file-1.dataset.aml
| |- dataset-file-n.dataset.aml
|- dashboard-directory
| |- dashboard-file-1.dashboard.aml (not supported yet)
| |- report-file-1.viz.aml (not supported yet)
|- index.aml

Within a project, there are two main files that we currently support: model and dataset

  • Model file correlates with a native table in your database or a SQL query. Within a model file, Analysts will define all the dimensions, measures that will appear in the UI for users to explore and get insights.
  • Dataset file is the collection of related models and how they're linked with each other. Within a dataset file, Analysts will decide which models should be included in the dataset for users to explore and build reports.
  • Other than model and dataset, there is index.aml file which stores the link/path to the dataset files that you allow your business users to explore from these datasets in reporting layer

Other than model and dataset, a project will soon contain dashboard file and visualization file to define dashboard and visualization in Reporting Layer (current not supported).

Guide to organize project files

An AML project is just a bunch of .aml files, so technically we can just order them in any ways we want. However, for consistency and ease of navigation, we can follow this structure:

|-- data_source
| |-- datasets
| | |-- name_by_team_or_usage
| |-- models
| | |-- name_by_source_applications
| | |-- name_by_usage
| | |-- ...


  • data_source: Models and datasets from different data sources should be separated into different parent folders.
  • datasets folder contains .dataset.aml files. It can be grouped by their usage, or the teams that it mainly serves
  • models folder contains .model.aml files. It is best to mirror the dbt project structure here.

Let us know what you think about this document :)