Semantic Layer Sync

Semantic Layer Sync synchronizes the data model of a semantic layer from Cube to BI tools. It's the easiest way to connect a BI tool to Cube.

Semantic Layer Sync programmatically connects a BI tool to Cube via the SQL API and creates or updates BI-specific entities that correspond to entities within the data model in Cube, e.g., cubes, views, measures, dimensions.

In general, here's how Cube entities match BI-specific ones:

Creating syncs

You can create a new sync by navigating to the Semantic Layer Sync tab on the BI Integrations page and clicking + Create Sync.

Follow the steps in the wizard to create a sync with any of supported BI tools.

Supported tools

Semantic Layer Sync supports the following BI tools:

• Apache Superset (self-hosted) and Preset (managed)
• Metabase (self-hosted and managed)
• Tableau (Cloud and Desktop)

Configuration

Under the hood, Semantic Layer Sync is configured using the semanticLayerSync option in the cube.js configuration file.

This function accepts a security context and returns an array of configured syncs. It can also be asynchronous, allowing for dynamic definition of syncs, e.g., loading the configuration from a remote API endpoint.

Each sync is configured with a mandatory name and a type as well as the config object with BI-specific credentials, e.g., a workspace URL and an API key. config also includes the database name that will be created and updated in the corresponding BI tool.

A sync can be disabled by setting active to false; such syncs will not run automatically. If active is undefined, a sync is considered enabled.

Example configuration with a single disabled sync:

module.exports = {
  semanticLayerSync: ({ securityContext }) => {
    return [
      {
        type: "superset",
        name: "Superset Sync",
        active: false,
        config: {
          user: "mail@example.com",
          password: "4dceae-606a03-93ae6dc7",
          url: "superset.example.com",
          database: "Cube Cloud: staging-deployment",
        },
      },
    ];
  },
};

Multitenancy

If multiple security contexts are defined via the scheduledRefreshContexts configuration option, semanticLayerSync can provide custom configuration for each of them.

You can synchronize the data model of each tenant to a different BI tool or a different database in a single BI tool, or implement another scenario that makes sense in your use case.

Example configuration for the case when each department wants have their data model synchronized to a dedicated database in a BI tool:

module.exports = {
  semanticLayerSync: ({ securityContext }) => {
    const department = securityContext.department;
 
    return [
      {
        type: "metabase",
        name: `Metabase Sync for ${department}`,
        config: {
          user: "mail@example.com",
          password: "4dceae-606a03-93ae6dc7",
          url: "example.metabaseapp.com",
          database: `Cube Cloud: ${department}`,
        },
      },
    ];
  },
};

Example confguration for the case when only admin data model should be synchronized with a couple of BI tools:

module.exports = {
  semanticLayerSync: ({ securityContext }) => {
    if (securityContext.role === "admin") {
      return [
        {
          type: "superset",
          name: "Superset Sync",
          config: {
            user: "mail@example.com",
            password: "4dceae-606a03-93ae6dc7",
            url: "superset.example.com",
            database: "Cube Cloud: sls-test (admin)",
          },
        },
        {
          type: "preset",
          name: "Preset Sync",
          config: {
            api_token: "07988f63-c200-499e-97c9-ba137d8918aa",
            api_secret: "c19fbab4fd4945899795d32898f2e1165bef8e5ee653",
            workspace_url: "12345678.us1a.app.preset.io",
            database: "Cube Cloud: sls-test (admin)",
          },
        },
      ];
    } else {
      return []; // Only sync the 'admin' data model
    }
  },
};

Apache Superset

Data model is synchronized via Superset API (opens in a new tab) which uses a user name and a password for authentication. You can use your own user name and password or create a new service account. You can copy a url at any page of your Superset workspace.

Example cube.js confguration file for Superset:

module.exports = {
  semanticLayerSync: ({ securityContext }) => {
    return [
      {
        type: "superset",
        name: "Superset Sync",
        config: {
          user: "mail@example.com",
          password: "4dceae-606a03-93ae6dc7",
          url: "superset.example.com",
          database: "Cube Cloud: production-deployment",
        },
      },
    ];
  },
};

Preset

Data model is synchronized via Preset API (opens in a new tab) which uses API keys for authentication. You can generate a new API key in your user settings (opens in a new tab) in Preset to obtain an api_token and an api_secret. You can also copy a workspace_url at any page of your Preset workspace.

Example cube.js confguration file for Preset:

module.exports = {
  semanticLayerSync: ({ securityContext }) => {
    return [
      {
        type: "preset",
        name: "Preset Sync",
        config: {
          api_token: "07988f63-c200-499e-97c9-ba137d8918aa",
          api_secret: "c19fbab4fd4945899795d32898f2e1165bef8e5ee653499e92f083b3d088aecb",
          workspace_url: "12345678.us1a.app.preset.io",
          database: "Cube Cloud: production-deployment",
        },
      },
    ];
  },
};

Metabase

Data model is synchronized via Metabase API (opens in a new tab) which uses a user name and a password for authentication. You can use your own user name and password or create a new service account. You can copy a url at any page of your Metabase workspace.

Example cube.js confguration file for Metabase:

module.exports = {
  semanticLayerSync: ({ securityContext }) => {
    return [
      {
        type: "metabase",
        name: "Metabase Sync",
        config: {
          user: "mail@example.com",
          password: "4dceae-606a03-93ae6dc7",
          url: "example.metabaseapp.com",
          database: "Cube Cloud: production-deployment",
        },
      },
    ];
  },
};

When a sync is run, Metabase will send an email with a new login notification. You can ignore such emails, configure Metabase (opens in a new tab) to skip sending them, or use a service account with a different email address:

Tableau

Data model is synchronized via the Tableau API (opens in a new tab) which uses personal access tokens (opens in a new tab) for authentication. You can create a new personal access token (opens in a new tab) on the My Account Settings page.

You will also need to specify a region and a Tableau site name. Consider the following URL of a Tableau site: https://10ax.online.tableau.com/#/site/cubedev/home. In this case, the region would be 10ax and the site name would be cubedev.

Example cube.js configuration file for Tableau:

module.exports = {
  semanticLayerSync: ({ securityContext }) => {
    return [
      {
        type: "tableau",
        name: "Tableau Sync",
        config: {
          region: "10ax",
          site: "mytableausite",
          personalAccessToken: "cube-cloud",
          personalAccessTokenSecret: "HW8TFrBfJyen+JQleh0/bw==:1BvJLIti9Fud04rN021EfHMnh4yYD3p4",
          database: "Cube Cloud: production-deployment",
        },
      },
    ];
  },
};

When connecting a Cube Cloud data source to your Tableau workbook, you will be prompted to enter the user name and password for Cube Cloud. You can find them at the SQL API Connection tab of the BI Integrations page in Cube Cloud.

Running syncs

When the data model is updated, all configured syncs will automatically run.

You can also run a sync manually by navigationg to the Semantic Layer Sync tab on the BI Integrations page and clicking Start Sync next to a relevant sync.

During the sync, Cube will either create from scratch or update a database in the corresponding BI tool and the data model associated with it. Syncing a branch in development mode will create a separate database, leaving the one associated with the production branch intact.

Viewing history

You can view the history of runs for a particular sync by navigating to the Semantic Layer Sync tab on the BI Integrations page and clicking Show History next to a relevant sync.