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 is available in Cube Cloud on all tiers (opens in a new tab).
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:
Cube | BI tool |
---|---|
Deployment, branch | Database |
Cube, view | Dataset, table, data source |
Measure, dimension, segment | Column, dimension, metric |
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)
We're working on bringing support for more BI tools, e.g., Power BI and MicroStrategy. Please reach out to us (opens in a new tab) if you're interested in using Semantic Layer Sync with other BI tools.
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.
By default, multitenancy support in semanticLayerSync
is disabled. Please
contact support to enable multitenancy support in semanticLayerSync
for your
Cube Cloud account.
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.
Personal access tokens might be disabled in your Tableau site configuration. To enable them, navigate to the Settings page of your Tableau site and click Enable personal access tokens.
By default, personal access tokens are configured with an expiry period of 180 days. Please check your Tableau site configuration for details. To customize the expiry period, navigate to the Settings page of your Tableau site. Please also make sure to renew your personal access token in time.
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.
If data model is updated dynamically and the
schemaVersion
configuration option is used to
track data model changes, syncs will not automatically run. This behavior is
disabled by default. Please contact support to enable running syncs when the
data model is updated dynamically for your Cube Cloud account.
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.