AML Extend

Introduction

AML Extend is a function that is applied on an analytics object to produce a new object that takes on the original properties.

Consider the following example where a User model is extended for two use cases with different requirements:

Model users {
    // Details of these dimensions are omitted for brevity
    dimension id {} 
    dimension email {}
    dimension signed_up_at {}
    dimension first_logged_in {}
}

// Extend Users model and add a new dimension `activated_at`
Model activatedUsers = users.extend({
    // Details of this dimension are omitted for brevity
    dimension activated_at {},
})

// Extend Users model and hide the dimension `email` from end users
Model anonymizedUsers = users.extend({
    dimension email { hidden: true }
})

Without AML Extend, you would have to duplicate the model code multiple times, which is error-prone and requires careful maintenance.

Use cases for AML Extend

As your Holistics project grows in size and complexity, you’ll likely encounter similar situations where it’s useful to define and extend new analytics logic based on existing ones without duplication.

Some use cases for AML Extend:

• Implementing role-playing dimensions.
• Adapting analytics objects (models, datasets, dashboards) for use cases that require slight modifications.
• Defining a set of base models, datasets, dashboards and let different teams extend and build upon them.
• Sharing best practices and design patterns across your data organization.

Role-playing dimension

AML Extend enables you to implement role-playing dimensions in a concise way without duplication.

Let’s say that you have an Order model that contains information about when an order is first created and delivered. You want to enable users to analyze how many orders are created or received on a given date.

With AML Extend, you can define just one Date model, extend it into different models and use them in your dataset.

You can use AML Extend in the following way:

Model date {
  label: 'Dates'
  // Details of this dimension are omitted for brevity
  dimension date {}
}

Model createdDate = date.extend({
    label: "Created Date"
    dimension date { label: "Created at" }
})

Model receivedDate = date.extend({
    label: "Received Date"
    dimension date { label: "Received at" }
})

Dataset ecommerce {
  models: [orders, createdDate, receivedDate]
  relationships: [
    relationship(orders.created_date > createdDate.date, true) ,
    relationship(orders.received_date > receivedDate.date, true) ,
  ]
}

The dataset exploration will look like this:

Expose different data that contain the same information to different teams

Let’s say that you have a data model that represents employee information that you want to let the HR department and the Finance department use for different purposes.

Model employeeInfo {
    // Details of this dimension are omitted for brevity
    dimension employeeID {}
    dimension first_name {}
    dimension last_name {}
    dimension email {}
    dimension salary {}
}

You can put this data model into a dataset and share that to both departments.

However, the Finance department may be interested in certain dimensions, such as employee’s ID and salary, so that they can calculate relevant financial metrics. Exposing names/emails are not necessary, and can pose a security risk to your company.

You can duplicate the data model into one for HR and one for Finance, but you’ll have to pay extra efforts to ensure consistency when introducing new dimensions or changing existing dimensions.

With AML Extend, you can define the base model for employee information:

Model employeeInfo {
    // Details of this dimension are omitted for brevity
    dimension employeeID {}
    dimension first_name {}
    dimension last_name {}
    dimension email {}
    dimension salary {}
}

Then you can extend the base model and define additional dimensions or metrics for HR team.

Model employeeInfoHR = employeeInfo.extend({
    dimension employeeEngagementScore {}
    dimension recruited_from {}
})

// Add this model into a dataset and then expose the dataset to HR team

You can also extend the base model and hide irrelevant fields for Finance team.

Model employeeInfoFinance = employeeInfo.extend({
    dimension first_name { hidden: true }
    dimension last_name { hidden: true }
    dimension email { hidden: true }
    dimension performanceMetric {}
})
// Add this model into a dataset and then expose the dataset to Finance team

Combining values from a base model in extending model

Let's say that you have a product model that contains a description dimension, and you want to truncate this to the first 50 characters.

You can use SQL to re-define the dimension definition in AML Extend like this:

Model product {
    // Details of this dimension are omitted for brevity
    dimension product_description {
        // Other propreties are omitted for brevity
        defnition: @sql {{ #SOURCE.product_description }};;
    }
}

Model productWithShortDescription = product.extend({
    dimension product_description {
        definition: @sql left({{#SOURCE.product_description}}, 50);;
  }
})

How Extend works

AML Extend has the following properties:

• Inheritance. When you edit properties in the base objects, and these changes will be propagated to all extending objects.
• Additive. You can add new properties to the extending objects that do not exist in the base objects.
• Overriding. You can modify properties that the extending objects inherit from the base objects, without modifying the original properties.

AML extend will follow these steps when being used:

1. Clone the object that is being extended.
2. Create a new extending object from the extending code.
3. Merge and resolve any conflicts between these two objects. If a field is defined in both objects, AML always uses the version in the extending object (overriding).

Example:

Model users {
    label: 'Users'
    dimension id { ... }
}

Model activatedUsers = users.extend({
    label: 'Activated users'
  dimension activated_at { ... }
})

// Steps:
// 1. Clone the "users" object into a new copy (users_cloned)
// 2. Create a new extending object from the extending code block
//    { 
//      label: 'Activated users' 
//      dimension activated_at { ... }
//    }
// 3. Merge users_cloned to the newly extending object. 
// The 'label' field will be overridden by the new value.

// Final result:
Model {
    label: 'Activated users'
    dimension id { ... }
    dimension activated_at { ... }
}

Which analytics objects can I use AML Extend on?

AML Extend is designed to work with data models, datasets, dashboard elements and other as-code elements.