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:

Supported tools

Semantic Layer Sync supports the following BI tools. Check relevant pages for details on configuration and features for specific tools:

Apache Superset

Metabase

Preset

Tableau

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.

Configuration

Under the hood, Semantic Layer Sync is configured using the semantic_layer_sync option in the 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:

from cube import config
 
@config('semantic_layer_sync')
def semantic_layer_sync(ctx: dict) -> list[dict]:
  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:

from cube import config
 
@config('semantic_layer_sync')
def semantic_layer_sync(ctx: dict) -> list[dict]:
  department = ctx['securityContext']['department']
 
  return [
    {
      'type': 'metabase',
      'name': f"Metabase Sync for {department}",
      'config': {
        'user': 'mail@example.com',
        'password': '4dceae-606a03-93ae6dc7',
        'url': 'example.metabaseapp.com',
        'database': f"Cube Cloud: {department}",
      }
    }
  ]

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

from cube import config
 
@config('semantic_layer_sync')
def semantic_layer_sync(ctx: dict) -> list[dict]:
  if ctx['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 {
    # Only sync the 'admin' data model
    return []
  }

Running syncs

Cube automatically runs configured syncs every time a new build is deployed. Additionally, you can configure syncs to run on schedule. Finally, you can manually trigger any sync to run.

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.

On build

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

On schedule

You can use the scheduleInterval option to specify the interval for running a particular sync on schedule. This is useful for cases when you expect that a BI tool might be temporarily unavailable via its API; the next scheduled sync will likely succeed anyway.

from cube import config
 
@config('semantic_layer_sync')
def semantic_layer_sync(ctx: dict) -> list[dict]:
  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',
        'scheduleInterval': 'every 10 minutes'
      }
    }
  ]

The scheduleInterval option accepts values in the every [number] [period] format, where [number] can be any positive integer, and [period] can be any value from the following list: day, hour, minute, or days, hours, minutes.

Manually

You can also run a sync manually by navigating to the Semantic Layer Sync tab on the BI Integrations page and clicking Start Sync next to a relevant sync. This is convenient for working in the development mode.

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.

Cleaning up

You can remove the synced assets (e.g., data sources and datasets) from BI tools by clicking on ... of a respective tool and choosing Remove synced assets. It would remove the assets synced from the branch you're currently on, i.e., your development mode branch, shared branch, or main branch.