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.

Working in a Logical project? Logical projects support semantic defaults only — named Semantic Models are not available there. Jump to Logical projects: semantic defaults for the full workflow.

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:

• Named Semantic Models in Logical projects — semantic defaults are fully supported in Logical projects (see Logical projects: semantic defaults), but named Semantic Models cannot be created, imported, or exported there.
• Push to git
• Databricks metrics views
• OSI format in RE and FE.
• Direct Connect for Snowflake and Databricks
• Dbt semantic models (metrics flow)
• 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. 

Semantic defaults are available in both Physical and Logical projects. In a Logical project they are the only semantic layer — see Logical projects: semantic defaults.

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.

Named Semantic Models are available in Physical projects only.

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. 

The Semantic workspace is a Physical project feature. It is not present in Logical projects, where semantic defaults are edited directly on the diagram.

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. 

Physical and virtual relationships are treated as joins in a semantic model along with their respective columns (ensure that column pair mode is selected). Dependencies (DEPs) are not considered joins and will not be treated as such on a semantic model. 

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. Note that a named semantic model is 1:1 with a Semantic View in a snowflake project. Creating it as DDL will produce YAML wrapped in the SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML function and creating it from the semantic section will generate the raw YAML. 
• 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.

Reverse Engineering

SqlDBM allows RE of semantic model defaults and named semantic models. 

Import sources

Open Reverse Engineering → Semantic Model and choose a source:

Importing semantic defaults

A YAML whose top-level name is $$SQLDBM_DEFAULT (the format produced by Forward Engineering → Semantic defaults) is imported as project-level semantic defaults rather than a named model. Model-only sections — model-level metrics, verified queries, and custom instructions — are discarded with a warning. Defaults can only arrive via upload or paste.

How the import is applied

• Tables are matched by fully qualified name. Tables referenced in the YAML but missing from the project are auto-created, including columns, primary key, and semantic defaults.
• Columns are matched by physical name. Fields that reference a plain column are treated as physical; calculated expressions become semantic-only custom fields. Metrics and filters are always semantic-only.
• Attribute differences: a defaults import updates the shared defaults; a named-model import creates overrides on that model only. Physical attributes (e.g., data type) are never changed by a named-model import — the physical value is kept and a warning is raised.
• Relationships are matched against existing FKs, virtual FKs, and virtual joins. Unmatched relationships are created as project-level relationships (defaults import) or as local joins scoped to the model (named-model import). Range joins are not currently supported — a model containing one is skipped.
• Name conflicts: importing a model whose name already exists replaces the existing model in place.

Preview before you commit

Before anything is applied, a consolidated preview shows every change across all selected sources — new and replaced models, new tables and columns, default updates, overrides, relationships, removed items, and any warnings or errors. Warnings and errors are advisory and do not block the import; you can proceed or cancel.

After import, named models appear in the Database Explorer (under Semantic Views for Snowflake projects), and any warnings remain in the Errors & Warnings panel for review.

Safety guarantees

Semantic RE never deletes physical tables or columns, and a defaults import never removes constraints or relationships from the project. Only semantic-only items (custom fields, metrics, filters, local joins) omitted from the imported YAML are removed from the corresponding scope.

Logical projects: semantic defaults

Logical projects support the semantic defaults layer — you can annotate entities and attributes with analytical meaning directly in your logical model, forward-engineer those defaults, and carry them across when you export to or import from a Physical project.

Named Semantic Models are not supported in Logical projects. They cannot be created, imported, or exported there. Logical projects have no Semantic workspace, no Semantic Model Explorer or Design Canvas, and no Semantic Models group in the Database Explorer. Everything you define in a Logical project is a default — see The two-layer design.

What is supported

Defining semantic defaults in a Logical diagram

Defining semantic defaults in Logical projects works exactly as it does for physical projects, described in this article. Users can create metrics, dimensions, and filters and declare definitions using native SQL expressions. 

Forward Engineering semantic defaults from a Logical project

Forward Engineering of semantic defaults works exactly as it does in Physical projects. Open Forward Engineering, choose Semantic YAML, and on the Objects step select Semantic defaults and the entities you want. The generated YAML uses the reserved model name $$SQLDBM_DEFAULT and contains table-level defaults only. See Forward Engineering for the full set of options.

Export and import: Logical ⇄ Physical

Semantic defaults travel with your model when you move between project types. They are carried in the existing SQL Objects tab of the Export and Import dialogs.

Exporting a Logical project to a Physical project

• Run the export as usual (to a new or existing Physical project). Semantic defaults — Included, Semantic Type, Synonyms, SQL Expression, and table-scoped default metrics and filters — appear as additional properties on the relevant entity and attribute rows in the SQL Objects tab.
• Each property follows the usual Added / Updated / Removed markers and checkboxes. Removed defaults are unchecked by default, so you opt in to deletions.

Importing a Physical project into a Logical project

• Semantic defaults from the Physical project's tables and columns appear as additional properties on the matching entity and attribute rows in the SQL Objects tab, with the same Added / Updated / Removed behavior.
• Any named Semantic Models in the source Physical project are ignored — they do not appear anywhere in the Import dialog. Snowflake-specific Semantic View properties (schema assignment, DDL settings) are not imported either.
• The existing notice "Only objects and properties supported in Logical projects may be imported" continues to apply: anything a Logical project can't represent is skipped.

How attributes are matched

In both directions, SqlDBM reuses the column mapping established by the existing export flow, so defaults land on the column you expect on every subsequent round trip.

The first time semantic data moves between the two projects there is no mapping yet, so matching is done in two steps — both must succeed:

1. Entity match — the logical entity's physical name against the physical table name.
2. Attribute match — the attribute name against the column name, within the matched entity.

If no match is found, the attribute and its semantic defaults are shown as Added in the destination project rather than being dropped.

Tip: keep entity physical names and attribute names aligned across your Logical and Physical projects before the first export. Consistent naming is what lets the two-step match succeed and establishes the mapping that all later exports and imports rely on.

Concurrent working and merge 

When you merge a branch that touched semantic content:

• A new Semantic Models tab appears as a tab on the merge popup. The usual Added (green), Updated (yellow), and Removed (red) markers, and can be checked or unchecked like any other object. (Physical projects only — Logical projects contain no named Semantic Models.)
• Semantic defaults are merged as part of the table they belong to and are not independently selectable. They are displayed on the "Metadata" tab of columns they belong to. 
• Note that a semantic model must be merged together with the objects it references: if its related objects aren't included in the merge, the semantic model won't be merged either.