Blog

Building better semantic views for Snowflake Cortex Analyst

7 minute read

28 July 2026

As Snowflake continues to expand its native AI capabilities, Cortex Analyst and Cortex Agent have become powerful tools for natural-language analytics. A well-designed semantic view sits at the heart of these experiences: it connects business logic, metadata, and user intent to the underlying Snowflake objects that store your data.

What is a semantic view in Snowflake?

A semantic view is a structured YAML definition of your data domain that tells Cortex Analyst and other consumers of the semantic layer:

Which logical tables and base tables matter
Which dimensions, time dimensions, facts, and metrics to expose
How those tables relate to one another
Which reusable filters, descriptions, and synonyms should apply
How business terminology should map to the data model
How natural-language questions should be translated into correct SQL

It is essentially a translation layer between human questions and Snowflake SQL, helping Snowflake AI produce more accurate, governed outputs.

Structure of a Semantic view (YAML)

Below is a simplified example of the overall YAML structure, including logical tables, dimensions, time dimensions, facts, metrics, and relationships.

name: workforce_analytics 
description: Semantic view for HR and workforce reporting 
tables: 
- name: employees 
  description: One row per employee 
  base_table: 
    database: hr_db 
    schema: reporting 
    table: employees 
  dimensions: 
  - name: employee_id 
    description: Unique employee identifier 
    expr: EMPLOYEE_ID 
    data_type: VARCHAR 
    synonyms: 
    - emp id 
    - employee number 
  - name: department_id 
    description: Department key 
    expr: DEPT_ID 
    data_type: VARCHAR 
  time_dimensions: 
  - name: hire_date 
    description: Date the employee joined 
    expr: HIRE_DATE 
    data_type: DATE 
  facts: 
  - name: employee_count_fact 
    description: Row-level employee counting fact 
    expr: 1 
    data_type: NUMBER 
  metrics: 
  - name: employee_count 
    description: Total number of employees 
    expr: COUNT(*) 
 
- name: departments 
  description: Department dimension table 
  base_table: 
    database: hr_db 
    schema: reporting 
    table: departments 
  dimensions: 
  - name: department_id 
    description: Department key 
    expr: DEPT_ID 
    data_type: VARCHAR 
    synonyms: 
    - department key 
    - department id 
  - name: department_name 
    description: Name of department 
    expr: DEPT_NAME 
    data_type: VARCHAR 
    synonyms: 
    - department 
    - department name 
 
relationships: 
- name: employees_to_departments 
  left_table: employees 
  right_table: departments 
  relationship_columns: 
  - left_column: department_id 
    right_column: department_id 
  relationship_type: many_to_one

Metrics

Metrics define the aggregated business values that end users usually want to ask about, such as total sales, average order value, headcount, or attrition rate. In a semantic view, metrics sit above the row-level data and encode how a value should be calculated consistently whenever it is used.

This is an important distinction from facts. Facts represent row-level numeric values or atomic quantitative elements in a logical table, while metrics represent business-ready aggregations or derived calculations built for analysis. In practice, dimensions answer "by what", facts describe the underlying quantitative data, and metrics answer "what number should we report".

Metrics are especially useful because they centralise business logic. Instead of relying on every analyst or generated query to independently define revenue, employee count, or profit margin, you define the metric once in the semantic view and reuse it consistently across Analyst, Agent, and BI use cases.

metrics: 
- name: employee_count 
  description: Total number of employees 
  expr: COUNT(*) 
- name: average_tenure_years 
  description: Average employee tenure in years 
  expr: AVG(DATEDIFF('day', HIRE_DATE, CURRENT_DATE()) / 365.25)

You can also create derived metrics that combine logic across tables or reuse existing business definitions. This makes the metrics section one of the most important parts of the semantic view for ensuring that generated answers align with how the business actually measures performance.

Additional features to improve model quality

There are optional features you can include in your semantic view to improve the accuracy, consistency, and trustworthiness of Cortex Analyst and Agent.

Verified Queries

Verified queries allow you to provide example SQL statements that demonstrate:

How metrics should be calculated
Which joins are correct
What filters belong in every query
Edge cases or special logic

These examples guide the model’s reasoning and reduce mistakes.

verified_queries: 
- name: employee count by department 
  question: What is the employee count by department? 
  sql: | 
    SELECT department_name, employee_count 
    FROM __employees 
    GROUP BY department_name, employee_count 
    ORDER BY employee_count DESC

Custom Instructions

Custom instructions allow you to encode global rules and steer the model away from incorrect assumptions. These instructions help guide how Analyst or Agent should interpret your semantic layer and generate SQL.

Typical use cases include:

Enforcing naming conventions
Restricting cross joins
Defining what 'current year', 'active', or 'headcount' means
Limiting row counts
Specifying the correct fiscal calendar

module_custom_instructions: 
  sql_generation: | 
    Always join employees to departments using department_id. 
    Interpret headcount as employee_count unless the user specifies otherwise. 
    Use the organisation's fiscal year definition when answering year-based questions.

These dramatically improve reliability.

Filters

Filters allow you to define reusable constraints that Snowflake can automatically apply.

Common examples are:

Active employees
Exclude test data
Current period filters
Region or organisation specific rules

filters: 
- name: active_employees 
  description: Include only active employees 
  expr: STATUS = 'ACTIVE' 
- name: exclude_test_records 
  description: Exclude test employees 
  expr: EMPLOYEE_NAME NOT ILIKE '%TEST%'

Filters help to maintain consistent business definitions across all generated queries.

Conclusion

Semantic views are one of the most important components of a Snowflake Cortex Analyst or Agent implementation. The more clearly you define dimensions, facts, metrics, relationships, filters, and guidance, the more reliable and consistent the generated answers become. Starting with a basic model is fine, but adding metrics, verified queries, custom instructions, and filters turns your Snowflake AI into a more trustworthy analytics assistant that reflects your organisation's business logic.