Getting Started with AQL
This section provides the "minimal viable instructions" to allow you to start working with AQL.
Enabling AQL
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: [ ]
}
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
;;
}
}
![AQL Metrics in Dataset](https://cdn.holistics.io/docs/v4/amql/aql_metrics_dataset.png)
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 |