Blog

Building better semantic views for Snowflake Cortex Analyst

Schedule7 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. 

Subscribe to Altis

Join our mailing list to receive the latest updates, expert insights and event news.