Skip to main content

Modeling Workbench

info

Semantic authoring is in public beta and available for Team and Enterprise plans.
You need the Admin workspace role to create and edit semantic projects.

Semantic authoring lets you create and manage semantic data models directly in Hex — no third-party tool required. Semantic projects define a set of data models containing measures, dimensions, and relationships to provide a consistent, governed source of truth for self-serve analytics and AI across your workspace.

Create a semantic project​

  1. Navigate to Settings > Data Sources > Semantic projects.
Set up a semantic model in Hex
  1. Click + Semantic project.
  2. Enter a name, description, and select a data connection.

Use the Modeling Workbench​

The Modeling Workbench is where you define all the data models in your semantic project, as well as their relationships. You can create data models based on existing tables and their columns, use inline validation and autocomplete to help build your YAML file, and use the publish preview to review changes and understand their impact before deploying.

Create a model​

  1. In the Modeling Workbench, click Create a model.
  2. Add a Name and Description.
  3. Choose a table or query as the data source.
    • Use Choose table or the Data Browser on the left sidebar to explore your warehouse.
    • The default data source is a table, but you can also use a SQL query if you need to do any final filtering or transformation.

By default, Hex imports all columns from the underlying table as dimensions and imports column descriptions.

Create a semantic model

Each model is defined as a YAML configuration file, with fields specifying:

  • Source table
  • Dimensions
  • Measures
  • Relationships

When editing the YAML, the Modeling Workbench provides autocomplete suggestions for fields to help you write models faster and with fewer errors. Inline validation flags issues — such as missing definitions or incorrect formatting — so you can fix them before publishing.

See YAML specification for a detailed developer reference guide.

Model specifications

Publish a model​

When ready, click Publish to open the publish preview modal. The modal has four tabs:

  1. Checks - validates the model for errors or missing definitions.
  2. References - shows where the model is used in your workspace.
  3. Changes - lists updates since your last publish.
  4. Preview - lets you test the model and any changes in an Explore cell before publishing.
See semantic model references
Use explore cell to preview changes

Sync from GitHub (Optional)​

You can keep a semantic project in Hex synchronized with YAML files stored in GitHub for version control. The sync runs in a single direction - from GitHub into Hex.

view import instructions for syncing YAML from Github

To set up the sync from GitHub:

  1. Go to Settings > Data sources > Semantic projects.
  2. Open the three-dot menu next to your project.
  3. Select View import instructions to generate the steps and configuration you need.

Next steps​

Continue to Using semantic projects.

On this page