Semantic models introduction

info

• Semantic models are in Beta.
• Semantic models are available on the Team and Enterprise plans.

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

In Hex, semantic models 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. By not forcing every question to go through the semantic model, the model stays concise, and exploratory work is unburdened.

Currently, Hex can import models from the following semantic specs:

• dbt MetricFlow
• Cube
• LookML (in private beta, reach out to [email protected] to learn more)

Concepts

Semantic models 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 models, the key semantic objects are datasets, measures, dimensions, and joins.

Definitions

Term	Definition
Model	A grouping of datasets, connected to a single data connection. A connection can have multiple models across different semantic specs.
Dataset	A 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). Datasets contain measures and dimensions.
Measure	A 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(*).
Dimension	The 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.
Join	Also called “join relationships,” a join describes the relationship between two datasets, most commonly linked together using a shared common field. Note that users cannot define joins between datasets that belong to different models.

Hex imports semantic model files stored in GitHub, translating them into semantic objects (datasets, dimensions, measures, and joins) that represents 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.

Setting up a semantic model

info

• Users will need the Admin workspace role in Hex to create semantic models and the Admin role for the repository in GitHub containing the semantic model code.
• The recommended setup uses GitHub actions.

Creating a semantic model establishes a layer where logic is defined and reused throughout Hex. With Hex's semantic model integration, users can point directly to an existing semantic model in a GitHub repository that contains definitions for datasets, dimensions, measures, and joins. This allows Hex to import the semantic concepts, enabling 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.

Configuring a semantic model for import

info

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

• In GitHub, your semantic layer 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 models

2. Configure your semantic model and generate API token

• Click + Model
• Add a human-readable Name and Description
• Select your semantic model Type and Data connection

• Provide a Description for your API token
• Set the Expiration for your API token
• Submit to generate API token

4. 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

5. 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

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

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

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

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/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 model versions managed in GitHub.

Viewing and using the semantic model in Hex

Once the semantic model is imported into Hex, navigate and inspect its components, such as datasets, dimensions, and measures, with the Data browser. From the Data browser, create dynamic visualizations and perform ad-hoc analysis in an exploration.