Working with Semantic Models (Beta)

This feature may not be available by default and might need to be enabled upon request. Please contact your account manager for more information.

Semantic Models in SqlDBM give your team a single, governed analytical layer on top of your physical schema. Instead of every analyst, dashboard, and AI tool reinventing definitions for metrics like total revenue or active customers, you author those concepts once in SqlDBM and forward-engineer them into Snowflake as Semantic Views or convert to other semantic formats. Downstream tools and AI engines then work from a single, consistent definition of your business rules.

This feature supports Snowflake semantic properties and YAML format but it is not limited to Snowflake projects. All database types are supported. 

What makes this scalable across a large team is a deliberate two-layer design: define analytical semantics once as project-wide defaults, then build named Semantic Models that inherit those defaults and override only the specifics they need. The next section explains the pattern in detail — it's the most important concept to understand before you start authoring.

Beta scope and what's coming next

This is the first release of Semantic Models. The following capabilities are intentionally not yet available and are planned for upcoming releases:

• Reverse Engineering of existing Snowflake Semantic Views or YAML files into SqlDBM.
• Concurrent Working - semantic models can be started in branches but can not be merged at this time
• Logical projects and export to physical
• Databricks metrics views
• Additional enhancements to authoring, governance, and integrations.

What is a Semantic Model?

A Semantic Model is a project-level object that describes the analytical meaning of your data:

• (Logical) Tables — the database objects participating in the model (this includes views, dynamic tables, etc.)
• Semantic fields — the columns that matter for analysis, classified as Dimensions, Time Dimensions, or Facts (this includes calculated fields not present in the physical model)
• Metrics — reusable calculations such as SUM(order_total) or COUNT(DISTINCT customer_id)
• Filters — reusable WHERE-clause fragments scoped to a table
• Relationships — semantic joins between tables, with a configurable join type
• Verified Queries — trusted natural-language-to-SQL mappings for AI consumers
• Custom Instructions — free-form guidance for AI engines

Semantic Models live alongside your physical schema. Adding a table to a Semantic Model never modifies the physical model.

The two-layer design: defaults and overrides

Semantic metadata in SqlDBM lives at two levels. Understanding this is what separates a Semantic Model effort that scales to dozens of models and hundreds of tables from one that becomes a copy-paste maintenance burden.

Layer 1 — Semantic defaults (define once, reuse everywhere)

Semantic defaults sit on the physical objects themselves — tables, columns, and relationships in your project. For every column you define once:

• Logical name, semantic type (Dimension / Time Dimension / Fact), synonyms
• SQL expression (e.g., UPPER(C_NAME))
• Sample values, Is Enum
• Default table-scoped metrics and filters
• Default join type on each relationship

Defaults are shared across every Semantic Model in the project and are inherited automatically. They represent the canonical meaning of each table and column, independent of any specific business model.

Defaults are maintained on the Semantic View mode. 

Layer 2 — Named Semantic Models (override only what you must)

Named Semantic Models are built for specific business contexts — Revenue Analysis, Customer 360, Marketing Attribution. Each model:

• Inherits all defaults for free. A new model that adds the ORDERS table immediately picks up every synonym, semantic type, default metric, and default filter you already configured.
• Stores overrides only where it needs a model-specific deviation. Need a different logical name for ORDERS.AMOUNT in this one model? Override just that property. Everything else continues to inherit.
• Owns model-only assets that don't belong at the project level: model-level metrics, verified queries, custom instructions, local relationships, and per-model "hide from semantic model" choices.

Why this scales

• Define once, reuse everywhere. When you fix a synonym list or correct an SQL expression on the default layer, every Semantic Model that uses that column picks up the change automatically. No hunt-and-replace across models.
• Stay in sync. Defaults are the single source of truth. If the canonical definition of a column changes, you update one place.
• Override only the deltas. Model size stays small and reviewable — each model contains only the handful of things that genuinely differ from the shared baseline.
• Promote good overrides back to defaults. When a refinement in one model would benefit everyone, Push changes to default promotes it back to the shared layer with one click. All other models inherit the improvement.

Where you edit each layer

When a value differs from the default inside a named model, an override indicator (purple triangle) appears next to the field. The row context menu offers two actions that keep the two layers in sync:

• Reset to default — discard the override and re-inherit the current default.
• Push changes to default — promote the override to become the new default. Every other model that inherits that default will see the change.

Recommended workflow: As you onboard each table into the analytical surface, populate its defaults first — semantic types, synonyms, descriptions, the canonical SQL expression, and any always-on table metrics or filters. Only then create named Semantic Models for each business area. Done this way, a brand-new model that includes ten tables typically needs only a handful of overrides instead of hundreds of definitions.

Where Semantic Models live

You can reach the Semantic workspace three ways:

1. Left-hand navigation — click the Semantic icon.
2. Database Explorer — open the Semantic Views group (Snowflake projects only, show models as Semantic Views grouped under database.schema).
3. Diagram Explorer — double-click a Semantic View object placed on a regular diagram.

The Semantic workspace contains five areas:

1. Semantic Model Explorer — every Semantic Model in the project, listed alphabetically.
2. Semantic Diagram Explorer — a filtered explorer that shows only objects that can participate in a Semantic Model.
3. Semantic Model Diagram — shows participating tables and fields.
4. Semantic Model Properties editor — model-level properties like verified queries and custom instructions.
5. Semantic Object Properties Editor — object-level properties with an internal panel for each metric, filter, or sub-property. 

Creating a Semantic Model

You can create a new Semantic Model from any of these entry points:

• Database Explorer → Semantic Views group → Create new
• Semantic workspace → Semantic Model Explorer → Create new (context menu or bottom action)
• A diagram → empty Semantic View object → Create new

A new model is created with a default name like Semantic_Model_1. The Properties Editor opens automatically and the canvas opens empty in Semantic View.

You can also duplicate or delete a model from the same context menus. Deletion shows a confirmation pop-up; any Semantic View objects representing the model on diagrams are removed automatically.

Adding tables to a Semantic Model

In the Semantic workspace, drag a table from the Semantic Diagram Explorer onto the canvas, or right-click and choose Add to semantic model.

When a table is added:

• It appears on the canvas referencing the underlying physical object (no physical change is made).
• All columns are included as semantic fields by default. Uncheck the Included box for any column you don't want exposed.
• Physical PK/FK relationships are automatically converted into semantic joins (default join type Left).

Which object types can participate?

Supported in semantic contexts: any table-like object (e.g., view, mat. view, iceberg table).

The following objects are intentionally hidden from the Semantic Diagram Explorer, the Semantic canvas, and Semantic View Mode on regular diagrams (they remain visible in all non-semantic views): Stored Procedures, Functions, Sequences, File Formats.

Editing semantic fields

Select a table to open the Metadata Bottom Panel. Remember which layer you're editing:

• On a regular diagram in Semantic view → your edits become defaults and flow into every model.
• On the Semantic Model Design Canvas → your edits become overrides that apply to the current model only.

For each column you can configure:

Custom fields

Use the table's context menu → Add field to create a semantic-only field that is not bound to a physical column. Custom fields have editable data type and Allow nulls (metadata only) and can be deleted — they never affect physical DDL. This operation is possible in both Semantic View and Semantic Editor screens.

Relationships and joins

Relationships visible on the Semantic canvas come from two sources:

• Inherited — physical FKs and virtual relationships (VFK, VJ) defined in your physical model. Column pairs are read-only inside the Semantic Model; only the semantic Join type is editable.
• Local — created from the canvas context menu (Add join / Add Relationship → Join). Column pairs are fully editable. Local relationships are scoped to the current Semantic Model only and are marked with a local badge.

Available join types

Left (default), Right, Inner, Full, AsOf. 

Snowflake join types: Besides AsOf and Range, Snowflake joins default to equijoin regardless of the type selected. For readability, it is encouraged to designate the intended type (e.g., left, inner, full, etc). 

Snowflake constraint: For equijoin relationships in a named Semantic Model, both sides of the join must have a unique-key constraint (PK, Unique Key, VPK, or VBK). If none exists when you create a local relationship, SqlDBM auto-creates a model-level VBK for you. If a qualifying constraint cannot be created, error E-SM-14 appears in the Errors & Warnings panel.

AsOf constraint: On Snowflake, AsOf relationships must be m:1 or 1:m. A 1:1 cardinality

Hiding a relationship from a model

Select a relationship → Properties Editor → check Hide from semantic model. The relationship is removed from the canvas and from the model's Forward Engineering output. It still appears in the Semantic Diagram Explorer under each table, displayed with dimmed text so you can re-include it later. Hiding affects only the active Semantic Model.

To use a different set of join columns inside a specific model, hide the inherited relationship and create a new local join with the columns you need.

Metrics, filters, verified queries, and custom instructions

Open the Semantic Model Properties Editor to manage model-wide assets.

Metrics

• Model-level metrics belong to the whole model. Required: Logical name (unique within the model), SQL expression, Access modifier.
• Table-level metrics are scoped to a specific table. Add one from the table context menu → Add metric. Required: Name (unique within the table), SQL expression, Access modifier.

Filters

Add a filter from the table context menu → Add filter. Filters are table-scoped. Required: Name (unique within the table) and SQL expression.

Verified Queries

Verified queries are trusted natural-language-to-SQL mappings. Add one from the Semantic Model PE → Verified Queries.

• Each verified query has a default logical name VQ_1, VQ_2, etc. The logical name is internal only — it is not included in the Forward Engineering output.
• The Question field is the natural-language question, must be unique within the model, and is what AI tools match against.
• A required SQL expression delivers the answer.
• Optional: Verified at, Verified by, Use as onboarding question.
• Duplicate the query from the row action; the new copy is named <original>_1.

Custom Instructions

Free-form guidance for AI engines. Two fields are available — Questions categorization and SQL generation — and the contents flow through to the YAML output as module_custom_instructions. No validation is performed.

Validation note: SqlDBM does not parse SQL for metrics, filters, or verified queries. It only checks that required fields are present. All errors and warnings are reported in the Errors & Warnings panel, and Forward Engineering proceeds even when errors exist.

Semantic View objects on regular diagrams (Snowflake)

In Snowflake projects, every Semantic Model is also represented as a Semantic View object that you can place on any regular diagram.

• Drag a Semantic View from the Diagram Explorer onto a diagram to add it.
• The object displays a read-only metadata table (object_kind, object_name, base_table) listing tables first, then metrics, filters, and verified queries.

Forward Engineering

Open Forward Engineering and choose an output format:

• DDL — for Snowflake projects, this generates the Semantic View as a CALL SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML(...) statement that wraps the model's YAML. Run it against your Snowflake account to create the Semantic View.
• Semantic YAML — produces a Cortex Analyst–compatible YAML artifact you can hand to any consumer of the spec.

When Semantic YAML is selected, the Type & Settings section is hidden and the primary button changes to Generate YAML. The Objects step lets you choose between:

• Semantic model — multi-select one or more named models. A separate YAML file is generated per selected model.
• Semantic defaults — multi-select one or more tables. The generated YAML uses the reserved model name $$SQLDBM_DEFAULT and contains only table-level semantic defaults (no model-level metrics, verified queries, or custom instructions).

Validation errors are reported in the Errors & Warnings panel but do not block generation — the output proceeds with whatever is defined.

Concurrent working and merge (coming soon)

When you merge a branch that touched semantic content:

• A new Semantic tab appears as the last tab on the merge popup. It contains a single Semantic defaults line that is highlighted yellow when any default was changed or added on any table.
• Semantic defaults are merged as part of the table they belong to — they are not independently selectable.
• Named Semantic Models appear on the SQL Objects tab with the usual Added (green), Updated (yellow), and Removed (red) markers, and can be checked or unchecked like any other object.
• If you uncheck a table that a Semantic Model depends on, the Semantic Model is automatically unchecked and a tooltip explains why.