Skip to main content

Introduction to Semantic Model Sync

info
  • Semantic Model Sync is in beta.
  • Semantic Model Sync is available on the Team and Enterprise plans.

Semantic projects make self-service analytics easier by allowing data teams to encode business logic into reusable, drag-and-drop elements.

In Hex, semantic projects are:

  • Open: They are imported from common external specs that can be free and used for many purposes besides just Hex.
  • Flexible: They are designed to integrate seamlessly into notebooks and can serve as jumping-off points for deeper, frictionless, exploratory work. Hex semantic projects can be used alongside exploratory data analysis across notebooks and apps, enabling consistent measures without limiting exploration or experimentation.

Currently, Hex can import models via Semantic Model Sync from the following semantic specs:

Concepts​

Semantic projects are a collection of logical tables, columns, aggregations, and join relationships that can be shared to make self-serve analytics easier and more consistent. In Hex’s semantic projects, the key semantic objects are models, measures, dimensions, and joins.

Definitions​

TermDefinition
Semantic ProjectA grouping of models, connected to a single data connection. A connection can have multiple semantic projects across different semantic specs.
ModelA logical table of data that often maps directly to a table in the data warehouse, but can be the result of a SQL query too (like a database view). Models contain measures and dimensions.
MeasureA pre-defined aggregation (sum, count, max, min, avg, count distinct, median) or expression of multiple aggregations. Example: a “Conversion rate” could be SUM(CASE WHEN converted = TRUE THEN 1 ELSE 0 END) / COUNT(*).
DimensionThe logical columns you want to group ("slice and dice") and filter by. These can point to singular warehouse columns or can be arbitrary (non-aggregating) expressions.
JoinAlso called “join relationships,” a join describes the relationship between two models, most commonly linked together using a shared common field. Note that users cannot define joins between models that belong to different projects.

Hex imports Cube and MetricFlow semantic model files stored in GitHub, while Snowflake Semantic Views are stored in Snowflake. Hex translates the models into semantic objects (models, dimensions, measures, and joins) that represent data structures. These components can be selected from the Data browser, where users can access these objects through Explore to easily build queries by dragging and dropping the available dimensions, measures, and joins.

Importing a semantic model flow

Setting up Semantic Model Sync​

info
  • Users will need the Admin workspace role in Hex to import semantic models
  • For Cube and MetricFlow based semantic models, users will need Admin role for the repository in GitHub containing the semantic model code
tip

Creating a semantic project establishes a layer where logic is defined and reused throughout Hex. Users can point to existing semantic projects that contain definitions for models, dimensions, measures, and joins. Through Hex Semantic Model Sync, Hex imports the semantic concepts and enables users to explore using these predefined concepts.

Preparing for import​

dbt MetricFlow​

If you are using dbt MetricFlow, you will need to add some metadata to your YAML files before importing them into Hex. Read more here, along with Hex’s support coverage of MetricFlow features.

Cube​

You can read about Hex’s support coverage of Cube features here.

Snowflake Semantic Views​

You can read about Hex's support coverage of Snowflake Semantic Views here.

Configuring a semantic project for import​

Snowflake Semantic Views​

  1. Navigate to configuration settings in Hex
  • Go to Settings > Data sources > Semantic projects
Set up a semantic model in Hex
  1. Select Model Type: Snowflake
  • Add a human-readable Name and Description
  • Select your semantic project Data connection and Semantic View
Set up a Snowflake semantic view in Hex
  1. Sync your Semantic View
  • Allow a moment for the Semantic Views to sync, once complete, click Finish.

Cube and MetricFlow​

info

Before getting started, please make sure the following requirements are met:

  • In GitHub, your semantic files are stored in a repository.
  • In GitHub, you are an Admin of the repository. If you do not have Admin access, you will need to ask an Admin to add a GitHub secret before you can complete the setup process
  • In Hex, you have an Admin role.
  1. Navigate to configuration settings in Hex
  • Go to Settings > Data sources > Semantic projects
Set up a semantic model in Hex
  1. Configure your semantic project and generate API token
  • Click Import
  • Add a human-readable Name and Description
  • Select your semantic project Type and Data connection
Configure a semantic model in Hex
  • Provide a Description for your API token
  • Set the Expiration for your API token
  • Submit to generate API token
Generate an API token and GitHub actions file
info

For non-GitHub Git hosts, refer to the generated GitHub Actions YAML file as a guide for setting up in your Git host.

  1. Add the API token as a secret in GitHub
  • Open your GitHub repository, then go to Settings > Secrets and Variables > Actions > Repository Secrets
  • Select New repository secret
  • Copy the token name from Hex and paste it into GitHub as the secret Name
  • Copy token from Hex and paste in the Secret field
  1. Configure GitHub Action
  • Create a new branch in your repository
  • Create a new file .github/workflows/hex-semantic-layer-sync.yml
  • Copy workflow file from Hex and paste into the created file
  • Open a new pull request against your main branch
  • Merge your branch
Create a GitHub action

Check the Actions tab of the repository after pushing to the main branch to see if there were any errors or skipped objects.

Check your GitHub actions run

If there are no errors, check the Semantic projects section of Data sources settings in Hex to see when the last import job completed.

Check the semantic model in Hex

Click into the value in the "Latest update" column to view the import status and skipped output from the most recent import.

View the semantic model import status in Hex

Testing and importing the semantic model​

The provided GitHub Action workflow is configured to trigger differently based on the merge target:

  • Merge to dev branch: test the contents of the branch against the importer without saving the objects to your Hex workspace
  • Merge to main branch: run the import, materialize any found objects to your Hex workspace.

View the import results in the Actions tab in the GitHub repository. Click into your workflow run and navigate to the “Ingest Semantic Model" section.

Running the GitHub action when semantic model files change

Update the GitHub action to only run when specific files within a directory change. This is recommended if the semantic model files are in a larger repository that contain other unrelated files. See GitHub action documentation.

Re-running an import from the GitHub Actions UI

In order to trigger an import, go to GitHub → Actions → Rerun all jobs. An import cannot be triggered from Hex, since the model is pushed from GitHub to Hex. This flow keeps Hex in sync with the latest semantic project versions managed in GitHub.

Git based workflow​

It is possible to use any Git host (. BitBucket, GitLab) as long as the workflow is able to send a .zip file to Hex's IngestSemanticModel API endpoint.

An equivalent to GitHub Actions is BitBucket Pipelines and GitLab CI/CD. In order to set up a workflow similar to GitHub Actions, please refer to the GitHub Actions YAML file (the workflow file generated in Step #2 in Configuring a semantic project for import) as a guide.

Next steps​

Continue to Using semantic projects.

On this page