Beta
Define in code is currently in beta. Workspace admins can request access for their workspace using this form.
Benefits of a code-based workflow
- Collaborate using pull requests and reviews
- Version control
- Reuse and copy definitions between workspaces
- Align with your existing development workflows
How it works
YAML
Define your semantic model in YAML files.
Github
Connect your Steep workspace to a GitHub repository.
Sync
Merge pull request with new code definitions. Steep instantly updates your model.
File structure
Use one YAML file per module to keep your model organised and easy to maintain.
Cache
Whenever a metric definition is updated, the metric cache is also refreshed.
Getting started
1. Connect a data source
Learn how to connect a data source →
2. Add your first YAML definition
3. Set up a GitHub repository
Create a dedicated repository for your semantic model.
4. Install the Steep GitHub app
Navigate to the Code page under Settings
Have you already connected another workspace to your GitHub account?
Connect to GitHub and choose to Install Steep Githubapp
Choose a repository (one repo per workspace) and a branch (we recommend main )
5. Push to main
Each push triggers Steep to parse your YAML files and update the semantic model.
6. Explore in Steep
Once synced, your metrics are ready to use in explorations and reports. Updates apply instantly.
Best Practices for a code-based workflow
- Keep YAML files modular (one module per file)
- Use meaningful metric identifiers you want to keep long term. Changing an identifier will result in metric being removed and recreated. Which risks impacting content through out Steep.
- Branch + PR workflow recommended
Changing repository
Please note
- When you change the repository or branch, all existing code definitions are replaced by the new definitions.
- If the new repository or branch is empty, your current modules will be converted to in app-defined modules.
Change repository or branch:
- Go to Code
- Select Edit next to your repository and branch
- Edit and Save
Remove a GitHub connection
When disconnecting the GitHub app, all definitions are kept and are converted into app-based definitions.
Go to Code
Edit your GitHub connection
Select Disconnect from GitHub
GitHub app will be disconnected, and all modules defined in code will automatically be converted to app-defined modules.
Combining UI and code definitions
You can mix code-defined and app-defined blocks (modules, dimensions, join paths and metrics) in the same workspace.
Use code where you need version control and structure — and the app where you want speed and flexibility.
Code-defined blocks
- Visible in the Steep app but locked for editing.
- Must be edited in code.
- You can build app-defined metrics or entities on top of code-defined modules.
App-defined blocks
- Can be edited directly in the Steep app.
- Metrics can’t be defined in code using a app-defined module.
Join paths
You can join any combination of UI and code modules. Joins can only be edited where they were created.
Conflict handling
- If a metric or module has the same identifier in both code and app → code will overwrite the app-defined metric or module
- If a join path exists in both code and the Steep app → code will overwrite the app-defined join path
Export code-definitions
Migration guide
Follow our step-by-step guide:
Modules
If you want to migrate modules define in the app to code, you can export modules one at a time.
Go to Modules and select a module.
Open the Code tab. Choose to copy or export the code definition.
This will export the entire module, including its dimensions, join paths, and metrics.
Metrics
You can view and copy a code snippet for an individual metric.
- Go to the Metric and open the About tab.
- The code snippet is shown under Code definition.
Metric code definitions are always part of a module.
To get the complete code for the module (including the module itself, its dimensions, and metrics), go to Model → Modules and export the corresponding module.
Staging workflow
When defining metrics in code, you may want a safe place to verify any changes before rolling them out. A simple way to do this is to use Git branches together with an internal staging Steep workspace.
Suggested setup
- Connect one or several workspaces to the main branch of your repository
- Connect an internal testing workspace to a staging branch
- Base all pull requests on the staging branch, ensuring changes can be tested safely in the testing workspace after merge
- Once everything looks good, merge
staging → mainto publish the changes to all connected workspaces
Alternative workflow
If you prefer to keep main as your default branch for pull requests, you can instead:
- Connect your testing workspace to main
- Connect your other workspaces to a published or production branch
- Publish changes by merging from
main → production
This workflow helps you move fast while staying confident in every update.
Multi-workspace setup
You can connect multiple workspaces to the same code-defined semantic model. This makes it easy to spin up new workspaces from the same definitions and manage updates for all workspaces from a single source of truth.
How to set it up
- Connect your first workspace to the Steep GitHub app.
- For each additional workspace, select Use existing GitHub connection
Beta limitations
We’re releasing the first beta version of Steep semantic definitions in code. In this version, the following cannot yet be defined in code:
- All metric types can be defined in code except derived ratio.
- Metrics can be defined in code except advance settings such as:
- Cohorts
- Cache time
- Teams permissions
- Entities
- Targets
You can use the Steep app to cover these gaps. Code and app-based definitions work seamlessly together, for example:
- A metric defined in code can drill down to an app-defined entity.
- You can build derived metrics in the app based on code-defined metrics.
This way, you can combine the flexibility of code with the full functionality of the Steep app.