AML Dataset Fields

Knowledge Checkpoint

This documentation assumes you are familiar with the following concepts:

• Dimension in Dataset
• Metrics introduction
• Cross-model Reference
• Cross-model Calculations

Introduction

To enable cross-model calculations and have a logical structure for the analytics codebase, we can also create Dimensions and Metrics within a Dataset:

• Dataset Dimension is analogous to Model Dimension
• Dataset Metric is analogous to Model Measure. However, Dataset Metric has more functionalities than Model Measure.

However, their definition and usage are different from those of the Model's counterparts.

Dimension

In Dataset Dimension, you can combine dimensions from one or more models. In general, Dataset Dimension's declaration is similar to that of Model Dimension, except for an extra model parameter that specifies the source model of the cross-model reference.

Parameter Definition

Parameter name	Description
label	Specifies how the dimension will appear in the exploration UI
type	Specifies the data type you want to apply to the dimension. Possible values: 'text', 'number', 'date', 'datetime', 'truefalse'
description	Describes the semantic of the dimension
hidden	Hides the dimension from the Exploration interface of Dataset and Report. This is not a Security Feature
model	Specifies the source model of the cross-model reference. The dimension will also appear under this model in the exploration UI.
definition	Determines how the dimension will be calculated using SQL-based syntax or AML syntax.

Example of Dataset Dimension Definition

Dataset e_commerce {
  (...)

  dimension full_name {
    model: users 
    type: 'text'
    label: 'Full name'
    definition: @aql concat(users.first_name, ' ', users.last_name);;
  }

  dimension age_by_year {
    model: users 
    type: 'text'
    label: 'Full name'
    definition: @aql date_diff('day', users.birth_date, @now) / 365;;
  }
}

Metric

Dataset Metric represents an aggregation that is calculated across one or more models. Dataset Metric's declaration is similar to that of Model Measure, except that it is only written using AQL.

Parameter Definition

Parameter name	Description
label	Specifies how the measure will appear in the Ready-to-explore Dataset
type	Specifies the data type you want to apply to the dimension. Possible values: 'number', 'date', 'datetime'
description	Describes the semantic of the measure
hidden	Hides measure from the Exploration interface of Dataset and Report. This is not a Security Feature
aggregation_type	Specifies the aggregate function of the Metric. Supported functions: count, count distinct, sum, avg, max, min, max, median, stdev, stdevp, var, varp, custom (for when the expression in definition is not already an aggregation). This is optional.
definition	Determines how the metric will be calculated using AQL expressions

Example of Dataset Metric Definition

Dataset ecommerce {
  (...)

  // 1. Simple aggregation
  metric count_orders {
    label: 'Count Orders'
    type: 'number'
    definition: @aql count(orders.id) ;;
  }

  // 2. Cross-model aggregation:
  metric sum_order_value {
    label: 'Sum Order Values'
    type: 'number'
    definition: @aql sum(order_items, order_items.quantity * products.price) ;;
  }
}

Notes

Dataset Dimension vs. Model Dimension

Even though it is possible to define dimensions in both Dataset and Model, we recommend the following:

• If the dimension transforms fields within the same model, it should be a Model Dimension.
• If the dimension transforms fields across multiple models, it should be a Dataset Dimension.

Dataset Metric vs. Model Measure

Similarly, even though it is possible to define a certain aggregation in both the Dataset and Model levels, we recommend the following:

• If the aggregation transforms fields within the same model, it should be a Model Measure.
• If the aggregation transforms fields across multiple models, it should be a Dataset Metric

As mentioned earlier, although Dataset Metric is analogous to Model Measure, it is actually much more powerful. For a more extensive discussion of AQL Metrics, please refer to the AQL Metrics section in our document.