Getting Started with AQL

This section provides the "minimal viable instructions" to allow you to start working with AQL.

Enabling AQL

info

Please note that users who sign up on or after ​April 19, 2024​ will have AQL enabled by default and can skip this step.

Users who signed up before this date will need to manually add the version flagging to the Dataset as instructed below.

For now, enabling AQL for your dataset involves a simple process of adding version flagging at the dataset level. You just need to incorporate a version flag in your dataset definition as: __engine__: 'aql'.

This will activate AQL within your specified dataset while other datasets continue to operate using the prior engine.

Dataset aql_dataset {
  __engine__: 'aql' //turn this Dataset to using AQL Engine
  data_source_name: 'your_datasource_name'
  models: [ ]
  relationships: [ ]
}

Important Note

If you signed up before ​April 19, 2024, we suggest creating a duplicate of the dataset you wish to apply AQL to for backward compatibility. You can then add version flags to this cloned dataset. Once you've tested AQL on the clone, you are free to enable AQL for your main dataset.

If you find that the new AQL engine impacts your existing reports, you can conveniently remove the version flags from the concerned dataset.

Where to define AQL Expression

AQL Expressions can be defined at two main levels: inside Dataset Definition or adhoc in a Dataset Explore

Inside Dataset definition

AQL Expressions, when defined within a Dataset, are visible to all end-users who have permissions to access that dataset.

Dataset ecommerce_aql {
  __engine__: 'aql'
  models: [ ]
  relationships: [ ]
  // Define AQL Dimensions here
  dimension aql_dimension {
    model: model_of_dimension
    label: 'AQL Dimesion Label'
    type: 'text' | 'number' | 'datetime' | 'date' | 'truefalse'
    description: 'AQL Dimension description'
    definition: @aql
      // AQL definition here
    ;;
  }

  // Define AQL Metrics here
  metric aql_metrics {
    label: 'AQL Metrics Label'
    type: 'text' | 'number' | 'datetime' | 'date' | 'truefalse'
    description: 'AQL Metrics description'
    definition: @aql
      // AQL definition here
    ;;
  }
}

Inside Model definition

AQL Expressions can be defined inside a Model as a Dimension or Measure

Model model_name {
  data_source_name: 'your datasource name'
  dimension dim_name {
    label: 'Dim Name'
    type: 'text' | 'number' | 'datetime' | 'date' | 'truefalse'
    definition: @aql
      //aql_expressions_here
    ;;
  }

  measure measure_name {
    label: 'Measure Name'
    type: 'text' | 'number' | 'datetime' | 'date' | 'truefalse' 
  definition: @aql
      //aql_expressions_here
    ;;
  }
}

Ad-hoc via Dataset Exploration

When AQL Expressions are defined on an ad-hoc basis during Dataset Exploration, they're only retained if the exploration is saved as a Report.

This ad-hoc approach is beneficial for quick calculations or when users, who don't have access to the modeling layer, need to conduct quick analysis.

Types of AQL Fields

An AQL Expression could be used as the definition of Dimension or Metrics.

AQL Metrics

AQL Metrics are aggregations computed over a dataset. This aggregation results in a singular value that quantifies an attribute or process within the data.

Metrics Example

• active users
• monthly recurring revenue (mrr)
• sales

AQL Metrics syntax:

metric aql_metrics {
  label: 'AQL Metrics Label'
  type: 'text' | 'number' | 'datetime' | 'date' | 'truefalse'
  description: 'AQL Metrics description'
  definition: @aql
    // AQL definition here
  ;;
}

In Holistics, both Measures and Metrics return a single value. However, they differ in their scope and complexity.

• Metrics allow cross-model calculations and can be used at the Dataset level, providing broader and more complex analyses.
• In contrast, Measures are defined at the Model level and support only single-model calculations, making them suitable for simpler, model-specific computations.

Parameter name	Description
label	Specifies how the metrics will appear in the Dataset
type	Specifies the data type you want to apply to the measure (currently Holistics only support text/number/date/datetime/truefalse)
description	Add metrics description
definition	Determines how the measure will be defined or calculated based on the AQL Expressions

AQL Dimensions

AQL Dimensions are categories or characteristics used to segment, classify, or contextualize data. They provide the perspectives or axes by which you can analyze or aggregate facts (measurable quantities) in your data.

Dimensions example

• Age Group
• Acquisition Cohort
• Country Name

AQL Dimension Syntax:

dimension aql_dimension {
  model: model_of_dimension // only require if it's defined in Dataset instead of model
  label: 'AQL Dimesion Label'
  type: 'text' | 'number' | 'datetime' | 'date' | 'truefalse'
  description: 'AQL Dimension description'
  definition: @aql
    // AQL definition here
  ;;
}

In Holistics, AQL Dimensions can be defined at both the Model and Dataset levels. However, there are key differences:

• When defining a Dimension in a Dataset, you enable cross-model calculations. This approach requires specification of the model that will house the dimension.
• Conversely, defining a Dimension within a Model limits calculations to that single model and doesn't necessitate specifying a storage model, as it's inherently linked to the model where it's defined.

Parameter name	Description
model	Model that stores the dimension and will be used as the context of the dimension
label	Specifies how the dimension will appear in the Dataset
type	Specifies the data type you want to apply to the dimension (currently Holistics only support text/number/date/datetime/truefalse)
description	Add dimension description
definition	Determines how the dimension will be defined or calculated based on AQL Expressions