Dynamic Data Sources & Schemas for Embedded Analytics

BETA FEATURE

This is a Beta feature. The documentation and feature may change rapidly. Contact [email protected] to try it out.

Introduction

When implementing embedded analytics, you may have customers with their own separate databases (or schemas). In this case, you'll want to configure your embedded dashboard to dynamically connect to the appropriate database based on which user is viewing it.

This post explains how to do that using our Dynamic Data Sources mechanism.

Use Case: Dynamic Data Source

1. Connect databases

First, make sure you connect all databases of your customers to Holistics.

The data source name will be used to identify which database to connect to at later steps, so you should use a unique and meaningful name for each data source.

2. Create user attributes

Before using user attributes data_source to dynamic datasource, you must define it in Holistics. See: User Attributes Documentation

3. Create a client_data_source variable in your AML codes

Go to the Development tab, create a new file embedded_variables.aml and add the following code:

const client_data_source = if (H.current_user.data_source) {
                            H.current_user.data_source
                          } else {
                            'default_data_source'
                          }

Tips:

• You can name the file anything you want, as long as it ends with .aml.
• You can name the variable anything you want, as long as it's a valid AML variable name.

4. Modify the embedded dashboard's dataset code

Modify the dataset code that powers the embedded dashboard to use this data_source variable:

Dataset dynamic_client_dataset {
  label: 'Dynamic Client Dataset'
  data_source_name: client_data_source
  models: [ orders ]
  relationships: [ ]
}

4. Pass data source name in the backend

When generating the embedded payload on your backend app, you can calculate and pass in the appropriate data source depending on your currently logged-in user.

// Embedded payload
embedded_payload = {
  permissions: {},
  user_attributes: {
    data_source: [ 'dev_data_source' ]
  }
}

Use case: Dynamic Schema

1. Create user attributes

Before using user attributes schema to dynamic schema, you must define it in Holistics. See: User Attributes Documentation

2. Create a client_schema variable in your AML codes

const client_schema = if (H.current_user.schema) {
                            H.current_user.schema
                          } else {
                            'default_schema'
                          }

Tips:

• You can name the variable anything you want, as long as it's a valid AML variable name.

3. Modify the embedded dashboard's data models

• For TableModel

Model dynamic_model {
  type: 'table'
  data_source_name: 'my_wh'
  table_name: '${client_schema}.cities'
}

• For QueryModel

Model dynamic_model {
  type: 'query'
  data_source_name: 'my_wh'
  query: @sql
    select *
    from ${client_schema}.cities
  ;;
  models: []
}

4. Pass schema name in the backend

// Embedded payload
embedded_payload = {
  permissions: {},
  user_attributes: {
    schema: [ 'your_schema_name' ]
  }
}

How it works

The dynamic feature works through a simple two-step process:

1. First, it creates a variable with a predefined path that acts as a placeholder
2. Then, when you send a JSON payload to Holistics, the system locates the variable using this path and dynamically replaces it with the actual value from your payload

This allows you to flexibly change data sources/schemas at runtime based on the values you provide.

Supported variables

H.current_user.data_source & H.current_user.schema

The H.current_user.data_source & H.current_user.schema variables allows you to define custom attributes that can be dynamically set through the embedded payload.

You pass those values in the embedded payload:

embedded_payload = {
  permissions: {},
  user_attributes: {
    data_source: 'embed_datasource',
    schema: 'embed_schema'
  }
}

Then you can reference those values in the model's query, table_name or dataset, model's data_source_name, etc:

Model dynamic_model {
  type: 'query'
  data_source_name: 'my_wh'
  query: @sql
    select *
    from ${client_schema}.cities
  ;;
  models: []
}

Testing in Embed Sandbox

You can use embed sandbox to test your dynamic data sources, schema setup