Create and Manage Semantic Models

Use the Semantic Web UI to create workspaces and add, validate, and publish semantic-model YAML files. A regular warehouse user can view published models. The warehouse admin user is required to change models or workspaces.

For definitions and YAML field reference, see Semantic model concepts.

Before you start

Make sure you have:

• An MCP Connection URL for a VeloDB Cloud warehouse.
• The warehouse admin username and password.
• The physical tables and columns that the semantic model will reference.
• A calendar table if you want to use period-over-period or year-over-year metrics.

Create and publish your first model

1. Open a workspace

1. Append /web to the MCP Connection URL. For example, open https://<warehouse-id>.<region>.aws.velodb.cloud/mcp/web.
2. Log in to Semantic Web UI with the warehouse admin username and password.
3. Select a workspace from the selector in the top bar. To create one, click + New Workspace and enter a name.

The model management page for the selected workspace is /mcp/web/models?workspace=<workspace-name>. It displays Active Files on the left and Staging on the right.

Note:

A workspace name must start with a letter and contain only letters, digits, and underscores. For example, marketing or finance_v2.

2. Add a semantic-model file

In the Staging panel header, click + New. Enter orders.yaml, paste the following definition, and click Create:

---
semantic_model:
  name: orders
  db_table: dw.orders
  defaults:
    agg_time_dimension: order_date

  entities:
    - name: order_id
      type: primary
      expr: order_id

  dimensions:
    - name: order_date
      type: time
      type_params:
        time_granularity: day
    - name: channel
      type: categorical

  measures:
    - name: total_amount
      agg: sum
      expr: amount
    - name: order_count
      agg: count
      expr: order_id

You can also click Upload in the Staging panel header to upload one or more .yml or .yaml files. Creating, uploading, editing, or deleting a file adds a pending change to Staging. It does not change the active model used by queries.

3. Add the time configuration

In the Staging panel header, click + New again. Enter project.yaml, add the calendar configuration, and click Create:

---
time_config:
  calendar:
    - table: dw.dim_date
      column: date_id
      grain: day

The calendar table is used for period-over-period and year-over-year metrics.

4. Validate the pending changes

Return to the model management page. In the header of the Staging panel on the right, click Validate. The Validate, Commit, and Discard buttons appear only when the workspace has pending changes.

Validation checks:

• YAML syntax and naming rules.
• Whether referenced tables and columns exist.
• MetricFlow semantic rules.
• Cross-model duplicate names and dependencies.

The validation result appears below the Staging panel. If validation fails, open the affected file from the model management page, correct it, click Save, and then click Validate again.

5. Commit the validated changes

After validation succeeds, click Commit beside Validate in the Staging panel header. Commit promotes all validated Staging changes to Active and triggers an automatic engine reload. You do not need to restart the MCP service.

After the reload completes:

1. Confirm that the files appear under Active Files.
2. Ask the AI agent to run check_service_health and confirm that the workspace is healthy.
3. Ask the AI agent to run list_metrics for the workspace and verify the published metrics.

Warning:

Commit is rejected with Staging must be validated before commit if the current Staging changes have not passed validation.

Understand workspaces and model storage

Workspaces

A workspace is an isolated container for semantic models. Each workspace has its own:

• Model files.
• Metric list. list_metrics only returns metrics from the selected workspace.
• MetricFlow query-engine instance.
• VeloDB Cloud warehouse connection pool.

Metrics in one workspace are not visible in another workspace. You can use workspaces to separate teams, projects, or environments.

Workspace states

Call check_service_health to see each workspace's runtime state:

State	Meaning	What causes it
healthy	The semantic model loaded successfully and its metrics are queryable.	The YAML files are committed, parsing succeeded, and MetricFlow is ready.
no_models	The workspace has no published model files.	The workspace is new, or all files are deleted.
not_ready	Model files exist but can not compile into a semantic manifest.	The model has a YAML, table, column, project configuration, or MetricFlow validation error.

After each reload, the service records the version number, metric count, and load status. Use the metric_count returned by check_service_health to confirm how many metrics are loaded.

Active and Staging stores

Each workspace has two storage layers:

Storage layer	Table	Purpose
Active Store	active_store_{workspace}	Contains committed models used by the query engine. Active files are read-only.
Staging Store	staging_store_{workspace}	Contains pending additions, edits, and deletions. Validated changes move to Active when you commit them.

The complete update flow is:

Step	Location	Action	Result
1	Staging panel header or file editor	Click + New, Upload, Save, or Delete.	The change is added to Staging without affecting active queries.
2	Staging panel header	Click Validate.	The service validates all pending changes.
3	Staging panel header	After validation passes, click Commit.	The validated files move from Staging to Active.
4	Automatic	Wait for the engine reload.	The service compiles the manifest and updates tool routing.

Semantic Web UI reference

Page	URL	Function
Log in	/mcp/web/login	Log in with a warehouse username and password. The default administrator username is admin.
Semantic Web UI home	/mcp/web	Select, create, or delete workspaces.
Model management	/mcp/web/models?workspace=<workspace-name>	View Active and Staging files. Add pending changes, validate them, and commit them.
File editor	/mcp/web/<filename>?workspace=<workspace-name>	Edit a YAML file and save the change to Staging.

The warehouse admin user can use these model-management actions:

Button	Location	Action
+ New	Staging panel header	Create a YAML file.
Upload	Staging panel header	Upload one or more YAML files.
Validate	Staging panel header, when pending changes exist	Validate all Staging changes.
Commit	Staging panel header, when pending changes exist	Publish validated Staging changes and trigger an engine reload.
Discard	Staging panel header, when pending changes exist	Remove all pending changes and keep the current Active version.
Reload	Top bar	Manually trigger an engine reload. Reload is normally automatic after Commit.

Permission model

Action	Warehouse admin user	Regular warehouse user
View semantic models	✅	✅
Query metrics with query_metric	✅	✅
List metrics with list_metrics	✅	✅
Upload, edit, or delete YAML	✅	❌
Validate, commit, or discard changes	✅	❌
Create or delete workspaces	✅	❌
Run read-only SQL with execute_query	✅	✅

Deploy the example workspace

The example workspace is optional and is not created automatically. On the Semantic Web UI home page, the warehouse admin user can click Deploy example to create the sample data and semantic models:

Content	Description
dw.orders	Orders table with 12 sample rows.
dw.users	Users table with 5 sample rows.
dw.products	Products table with 5 sample rows.
dw.dim_date	Calendar table used for timeline alignment and cumulative calculations.
Semantic-model YAML	orders.yaml, users.yaml, products.yaml, and project.yaml in the example workspace.

Example metrics include total_amount, order_count, avg_amount, unique_users, and user_count.

The deployment runs in the background. When it finishes, the example workspace becomes available to list_metrics and query_metric. If the example is not deployed, regular warehouse users can still use metadata discovery and read-only SQL.

Troubleshoot validation

Error message	Cause	How to fix
Table xxx does not exist	The table referenced by db_table does not exist.	Confirm the database and table names.
measure references missing column: dw.orders.xxx	A measure references a missing column.	Make sure expr matches the column name and case.
entity references missing column	An entity references a missing column.	Check the column or SQL expression in expr.
Duplicate measure 'xxx' defined in 2 models	Two models define a measure with the same name.	Rename one measure so its name is globally unique.
Duplicate semantic_model name	Two files use the same model name.	Rename one semantic model.
Did not find exactly one project configuration	project.yaml is missing or duplicated.	Keep one project.yaml that contains time_config.
'xxx' does not match '^(?!.*__)...$'	A name violates the naming rules.	Start with a lowercase letter, remove double underscores, and use at least two characters.
No staging changes to validate	The workspace has no pending changes.	Create, upload, edit, or delete a YAML file before clicking Validate.

If validation still fails:

1. Run DESCRIBE dw.orders to confirm that the physical table exists.
2. Confirm that column names and case match the YAML definitions.
3. Check the YAML indentation. Use spaces instead of tabs.
4. Confirm that every model, entity, dimension, and measure name follows the naming rules.

See also

• Semantic model concepts explains model fields and advanced metric definitions.
• Get Started explains how to connect an AI client and query the published metrics.