Singdata Semantic Views: The Complete Guide to a Governed Semantic Layer
How Singdata Semantic Views define relationships, dimensions and metrics once for BI, SQL and AI agents — plus modeling steps, change control, validation tests and documented limitations.
Two dashboards, one metric name, two numbers. Nobody is lying, nobody wrote bad SQL, and both reports were built by competent people. The divergence is structural: each report carries its own copy of the join, the filter, and the assumption about whether probationary staff count. Once an AI agent queries the same estate, it inherits the ambiguity and answers with full confidence.
This guide covers what a Singdata Semantic View is, how its four components fit together, how to build and validate a first view, how to govern metric definitions, and how to test consistency across BI, SQL and AI. It separates three kinds of statement: documented platform behavior, vendor-reported claims that a buyer should validate, and practical judgment about how to run the work.
What Is a Semantic View?
A semantic view is a logical data model object in Singdata Lakehouse that sits between physical table structures and business analysis. It defines table relationships, dimensions and metrics once, so every consumer — a SQL notebook, a BI tool, an AI agent — executes the same logic. The documentation frames it as solving two problems: business users query cross-table data in business terminology without writing JOIN and GROUP BY, and metric definitions are managed centrally so the same definition holds across the organization.
Semantic View vs. Database View vs. BI Dataset
The three objects live at different layers. A database view is a stored SQL query over physical tables: the join and filter logic is frozen inside it, and a second view over the same tables is free to encode different logic. A BI dataset is a report-tool artifact that typically carries its own copy of joins, filters and aggregation choices, which is why two tools can disagree about the same warehouse.
A semantic view is a schema-level logical model. Snowflake's documentation describes its semantic views as schema-level objects holding business concepts, metrics and relationships, queried in a SELECT statement; Singdata's object follows the same shape, declaring entities, relationships, dimensions and metrics once while the engine supplies joins at query time. The divergence problem is structural, not a competence problem: nothing in a database view or a BI dataset forces independent copies to agree.
The Four Components of a Singdata Semantic View
The documented model has four clauses, and each maps to a decision the modeler makes.
Logical Tables and Relationships
A logical table is an alias over a physical table plus a declared primary key. The documentation's example, depts AS doc_test.departments PRIMARY KEY (dept_name), maps the business entity "department" onto a physical table and nominates the identifying column. Foreign keys encode relationships, as in FOREIGN KEY (dept) REFERENCES depts (dept_name). Two rules apply at creation: referenced tables must be declared before the tables that reference them, and a foreign key that omits the target column defaults to the primary key, which fails on a type mismatch.
Dimensions and Computed Dimensions
Dimensions answer who, what, where and when. They support direct column mappings and expression-based computed dimensions such as YEAR(hire_date). The distinction matters for validation: a direct mapping can be checked against the column, while a computed dimension is where a granularity error hides — a hire year derived from a hire date is only correct if the date column's semantics are what you assume.
Metrics and Aggregation
Metrics are quantitative measures defined through COUNT, SUM, AVG, MIN and MAX. Conditional aggregations such as COUNT(CASE WHEN col = value THEN 1 END) are supported and are the right way to express subset metrics like an active-employee count, but they need validation because the case expression is where a boundary error hides. Two documented limits matter at design time: arithmetic-expression metrics and derived metrics that reference other metrics do not behave as written, detailed in the limitations section below.
Filters and the AI/Metadata Layer
Filters are predefined reusable conditions intended for the AI and metadata layer. They are not parameters to the semantic_view() query function. Query-time filtering happens in the outer WHERE clause, which requires the column you filter on to be defined as a dimension. First-time modelers routinely assume a named filter can be passed to the query; it cannot.
How to Model Your First Semantic View
Build one high-value domain, not the warehouse. The sequence below follows the documented agent guide's structure; the checkpoints are where a view either earns trust or quietly fails.
Step 1: Choose One Domain and Collect Business Knowledge
Pick a single analysis domain where divergent numbers already cause friction. Collect the questions the view must answer, metric definitions with inclusion and exclusion criteria, dimension granularity, implicit business rules such as excluding test accounts, and a glossary. The documentation is explicit that this step cannot be delegated to a tool. Skipping it means discovering that "employee count" is defined differently across reports only after the view goes live — the hardest class of issue to troubleshoot.
Step 2: Map Physical Tables to Logical Tables
Declare logical tables with primary keys, then foreign keys, ordering declarations so referenced tables come first. Script defensively: creating a view that already exists errors, so begin with DROP SEMANTIC VIEW IF EXISTS. Dimension and metric names accept both qualified (alias.name) and short (name) forms, equivalent when the name is unique within the view.
Step 3: Define Dimensions and Metrics
Define dimensions at the granularity report consumers actually use, and metrics with explicit inclusion and exclusion logic. The documented questioning approach fills these definitions: ask analysts how a number is calculated and which orders are included; ask consumers which dimensions they view data by and to what level; ask engineers what data should normally be excluded; ask business users which database field corresponds to a term like "active employees."
Step 4: Run the Validation Queries
Run the documented validation queries: a basic dimension with one or two metrics, checking row counts and value ranges; a computed-dimension query; and a comparison against an existing trusted report whose logic is already accepted. Creation success is not evidence of correctness — a view can be created without error and return numbers nobody recognizes.
Metric Scope, Grain, and Time Logic
The software does not decide what a metric means, at what grain it is defined, or which point in time governs its statistics. These are human decisions that the semantic view makes executable and consistent. Treat them as design inputs to settle before publication, not as questions to resolve after the first disagreement.
Defining Inclusion and Exclusion Rules
Decide what a metric counts. Does "employee count" include probationary staff? Does "order amount" mean the amount at placement, the amount net of refunds, or recognized revenue? Encode the answer as a conditional aggregation or a documented filter — the documentation's example excludes test accounts via an is_test flag — and give each rule an owner and a written rationale. Where two genuinely different questions exist, define separate, distinctly named metrics such as gmv, net_revenue and valid_order_amount, each with a comment explaining the difference, rather than one compromised number.
Choosing Grain and Time Semantics
Fix the point in time used for the statistic — order time, payment time or confirmation time — and fix the grain before metrics are published. Sequence of operations changes results: in Snowflake's reported evaluation of its own Cortex Analyst, generated queries that filtered a date range before calculating a rolling window metric produced incorrect numbers for the first days of the window. That is a vendor-reported evaluation of its own product, but the arithmetic point stands independently: filtering before and after a window are different calculations.
Who Owns Metric Definitions and How Change Control Works
Governance here is an operating model, not a policy document. Assign a named business owner per domain, with a data steward handling technical maintenance. The owner property on the view is a reasonable place to record the owner, and a version-controlled definition file is better. Route changes through a lightweight process: proposed change, impact review against dependent reports, versioned definition, rebuild path.
Change Control and Rebuilds
The rebuild constraint shapes change control rather than blocking it. ALTER SEMANTIC VIEW supports RENAME TO, SET PROPERTIES and UNSET PROPERTIES, but not adding or removing dimensions and metrics, and CREATE OR REPLACE SEMANTIC VIEW is not supported. Structural change therefore means exporting the definition, dropping the view, and rebuilding it.
The MCP workflow turns that constraint into a versioning habit: LH-desc-semantic-view exports a view as YAML for backup or comparison, and LH-create-semantic-view rebuilds it in a new environment. Treat that YAML export as the version artifact. A proposed change is reviewed against dependent reports, recorded as a diff in the export, and released through the rebuild path.
Access Control and Its Documented Boundary
Semantic views use standard GRANT and REVOKE, with read-only privileges only: SELECT and ALL. INSERT, UPDATE and DELETE are not supported, which fits an object you read from and never write to.
Two boundaries deserve an explicit flag in any governance review. The documentation covers view-level grants; it does not describe row-level or column-level policy behavior for semantic views. A requirement that a regional manager sees only their region's rows is therefore something to confirm with the platform, not to assume from GRANT SELECT. The documentation also does not describe how lineage is recorded for semantic views; information_schema.tables and DESC EXTENDED expose metadata and structure, but neither is a lineage record.
How Semantic Definitions Reduce AI-Agent Query Errors
An agent given a database schema and a question writes SQL from whatever it infers. A semantic view changes the input: the agent reads declared dimensions and metrics and queries through structured parameters. Singdata documents CZ-CLI and MCP tools for exactly this, and frames the accuracy benefit as a vendor claim. The honest limit is that grounding reduces error without removing the need for human validation of the definitions themselves.
The Documented Agent Workflow
The documented agent sequence is short. LH-brief-semantic-view teaches the agent which dimensions and metrics exist. LH-query-semantic-value then queries on demand, taking a view name, selected dimensions, selected metrics and optional filter conditions. If a required dimension is missing, LH-semantic-view-dim-add adds it without a rebuild. LH-desc-semantic-view exports YAML for backup or version comparison, and LH-create-semantic-view rebuilds the view in a new environment.
Singdata recommends LH-query-semantic-value as the agent query path because it avoids hand-written semantic_view() SQL; the structured call maps to an equivalent SELECT * FROM semantic_view(...) statement with an outer WHERE.
What Grounding Does and Does Not Fix
A semantic view makes the chosen meaning executable and consistent. It does not decide what a metric should mean, and an agent does not adjudicate meaning either: it selects whichever definition it finds and presents it with the same fluency as a correct one. A grounded agent that picks the wrong variant of "average salary" returns a confident, well-formatted, wrong answer.
Snowflake's own reported evaluation of Cortex Analyst illustrates the mechanism. In its published test set, a model missing a client's specific metric definition inferred its own calculation, while the semantic-model-backed system captured the definition and answered correctly. That is a vendor-reported evaluation of its own product, not an independent benchmark, but the failure mode it describes is general. The defense is the same for human consumers: distinctly named metrics with comments explaining the difference, plus validation against a trusted report.
How to Validate Consistency Across BI, SQL, and AI
Creation success is not evidence of correctness, and a single query path proves nothing about the others. The acceptance test is to issue the same metric query through three paths — a BI tool reading the view, direct semantic_view() SQL, and an agent via MCP or CZ-CLI — and require matching results on the same dimensions, filters and time window before calling the view production-ready.
A Consistency Test Matrix
Five cases cover the places where definitions drift. Record the expected value from the trusted report alongside the BI, SQL and agent results for each.
Test case | What it exercises | Expected source |
|---|---|---|
Dimension plus one or two metrics | Basic grouping and row counts | Trusted report |
Computed dimension (e.g. hire year) | Expression granularity | Trusted report |
Conditional-aggregation subset metric | Case-expression boundaries | Trusted report |
Cross-table metric | Engine-supplied join from declared foreign keys | Trusted report |
Time-window query | Date filtering and period boundaries | Trusted report |
Treat any mismatch as a definition or grain defect until proven otherwise. A cross-table discrepancy that appears as NULLs or implausible row counts usually traces to a foreign key declared incorrectly or not taking effect, not to the query tool.
Known Limitations to Design Around
Four documented limitations produce silently wrong numbers rather than errors, so each belongs in the acceptance checklist.
Arithmetic expression metrics do not error at creation but return only the first operand at query time.
Derived metrics that reference other metrics fail to resolve at creation.
Window function metrics do not error at creation but behave abnormally at query time and should not be used.
Named filters in the
FILTERSclause cannot be passed tosemantic_view(); filtering happens in the outerWHERE, and the target column must be defined as a dimension.
Where applicable, calculate the first three in the outer SQL of the semantic_view() query. Conditional aggregations such as COUNT(CASE WHEN ...) are supported and are the right way to express subset metrics, but validate them: the case expression is where a boundary error hides.
Frequently Asked Questions
Does a semantic view replace a database view? No. A database view stores a SQL query over physical tables; a semantic view is a logical model that declares relationships, dimensions and metrics, with the engine supplying joins at query time. They solve different problems and can coexist.
Do business users need SQL? Per the documentation, consumers query cross-table data using business terminology without writing JOIN and GROUP BY. Someone still has to model and validate the view.
What happens when a metric definition changes? Structural change requires exporting the definition, dropping the view and rebuilding it, because ALTER SEMANTIC VIEW cannot add or remove metrics and CREATE OR REPLACE is unsupported. Plan the change, review its impact on dependent reports, and version the YAML export.
Can agents modify a view? The documented MCP tools include LH-semantic-view-dim-add and LH-semantic-view-dim-del, which add or delete dimensions without a rebuild, plus LH-create-semantic-view from YAML. Whether an agent should hold those permissions is a governance decision, not a platform default.
Is row-level security covered? The documentation describes view-level GRANT and REVOKE with read-only privileges. It does not describe row-level or column-level policy behavior for semantic views, so confirm any row-level requirement with the platform before relying on it.
Further Reading and Next Steps
Run this checklist before declaring a view production-ready. Each item is pass or fail.
One high-value domain is in scope, with a written glossary and explicit exclusions.
Logical tables declare primary keys, and foreign keys reference declared tables with matching types.
Dimensions cover the granularity report consumers actually use; computed dimensions are validated.
Metrics carry inclusion and exclusion logic, and known definitional conflicts are resolved as separate, distinctly named metrics rather than one compromised number.
The five consistency tests match the trusted report across BI, SQL and agent paths.
The four documented limitations are either avoided or calculated in the outer SQL.
The YAML export is stored in version control with a named owner.
Access requirements beyond view-level grants are confirmed with the platform.
The authoritative references are Singdata's documentation set: Create Semantic View, Query Semantic View, Advanced Query Usage, Manage Semantic View, Integrate with AI, the agent guide and Best Practices. This guide reflects those documents as retrieved; re-confirm platform behavior against current docs before a production rollout.
Previous posts
https://www.singdata.com/company
https://singdata.com/trending/powerbi-date-difference-dax-calculations/