Modeling Workbench

info

• Semantic authoring is in public beta and available for Team and Enterprise plans.
• You need the Admin or Manager 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.

2. Click + Semantic project.
3. 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.

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.

Modeling Agent

The modeling agent helps you write and edit semantic models using natural language. Instead of manually writing YAML, you can describe the model you want and let the agent generate or update it.

The agent can generate new models from scratch or edit existing models with incremental changes. You can accept or undo these changes at any time.

Specific tables or Hex projects can be referenced directly with @ mentions.

The modeling agent can greatly speed up model creation and iteration. Always review the generated YAML to confirm that measures, dimensions, and relationships match your intended logic before publishing.

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.

History

The History page records a complete version timeline of your semantic project, including drafts, published versions, and agent-generated checkpoints.

You can:

• View and compare previously published versions.
• Compare your draft to a past version or agent checkpoint.
• Copy and paste definitions from any historical version back into your draft.

History provides version control directly in Hex, making it easy to experiment and iterate on natively authored semantic projects.

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.

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.