Cortex Analyst SQL vs Snowsight, step by step

0.1Copy the sample data and create a warehouse

USE ROLE SYSADMIN;
CREATE WAREHOUSE IF NOT EXISTS CORTEX_WH
  WAREHOUSE_SIZE = 'XSMALL' AUTO_SUSPEND = 60 AUTO_RESUME = TRUE;
CREATE DATABASE IF NOT EXISTS CORTEX_DEMO_DB;
CREATE SCHEMA IF NOT EXISTS CORTEX_DEMO_DB.TPCH_ANALYST;
USE WAREHOUSE CORTEX_WH;
USE SCHEMA CORTEX_DEMO_DB.TPCH_ANALYST;

-- The same three TPC-H tables you see in the screenshots
CREATE OR REPLACE TABLE ORDERS   AS SELECT * FROM SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.ORDERS;
CREATE OR REPLACE TABLE LINEITEM AS SELECT * FROM SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.LINEITEM;
CREATE OR REPLACE TABLE PART     AS SELECT * FROM SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.PART;

-- Informational primary keys (not enforced) help the GUI detect keys
ALTER TABLE ORDERS   ADD PRIMARY KEY (O_ORDERKEY);
ALTER TABLE LINEITEM ADD PRIMARY KEY (L_ORDERKEY, L_LINENUMBER);
ALTER TABLE PART     ADD PRIMARY KEY (P_PARTKEY);

The GUI reads primary and unique keys from table metadata, so declaring them here saves a step later. If SNOWFLAKE_SAMPLE_DATA is missing from your account, an ACCOUNTADMIN can add it:

-- Only if SNOWFLAKE_SAMPLE_DATA is missing (run as ACCOUNTADMIN)
CREATE DATABASE SNOWFLAKE_SAMPLE_DATA FROM SHARE SFC_SAMPLES.SAMPLE_DATA;

0.2Create a role for building semantic views

USE ROLE SECURITYADMIN;
CREATE ROLE IF NOT EXISTS CORTEX_ANALYST_ROLE;
GRANT ROLE CORTEX_ANALYST_ROLE TO USER <your_user>;
GRANT ROLE CORTEX_ANALYST_ROLE TO ROLE SYSADMIN;

USE ROLE SYSADMIN;
GRANT USAGE ON WAREHOUSE CORTEX_WH TO ROLE CORTEX_ANALYST_ROLE;
GRANT USAGE ON DATABASE CORTEX_DEMO_DB TO ROLE CORTEX_ANALYST_ROLE;
GRANT USAGE ON SCHEMA CORTEX_DEMO_DB.TPCH_ANALYST TO ROLE CORTEX_ANALYST_ROLE;
GRANT SELECT ON ALL TABLES IN SCHEMA CORTEX_DEMO_DB.TPCH_ANALYST TO ROLE CORTEX_ANALYST_ROLE;
GRANT CREATE SEMANTIC VIEW ON SCHEMA CORTEX_DEMO_DB.TPCH_ANALYST TO ROLE CORTEX_ANALYST_ROLE;

USE ROLE ACCOUNTADMIN;
GRANT DATABASE ROLE SNOWFLAKE.CORTEX_USER TO ROLE CORTEX_ANALYST_ROLE;

The role that creates a semantic view needs CREATE SEMANTIC VIEW on the schema, USAGE on the database and schema, and SELECT on the tables. SNOWFLAKE.CORTEX_USER is granted to PUBLIC by default, so the last statement only matters if your administrator revoked it.

0.3Check that a supported model is available

SHOW MODELS LIKE 'claude-4-sonnet' IN SNOWFLAKE.MODELS;

-- Only if your region does not host the models (run as ACCOUNTADMIN)
ALTER ACCOUNT SET CORTEX_ENABLED_CROSS_REGION = 'ANY_REGION';

Cross-region inference processes requests in another Snowflake region. Review it with your data governance team before you turn it on.

A1Create the semantic view

Run this as CORTEX_ANALYST_ROLE. It defines three logical tables, two joins, the business fields and one verified question.

USE ROLE CORTEX_ANALYST_ROLE;
USE WAREHOUSE CORTEX_WH;
USE SCHEMA CORTEX_DEMO_DB.TPCH_ANALYST;

CREATE OR REPLACE SEMANTIC VIEW TPCH_SALES_SV
  TABLES (
    orders AS CORTEX_DEMO_DB.TPCH_ANALYST.ORDERS
      PRIMARY KEY (o_orderkey)
      WITH SYNONYMS = ('sales orders', 'purchases')
      COMMENT = 'One row per customer order',
    lineitem AS CORTEX_DEMO_DB.TPCH_ANALYST.LINEITEM
      PRIMARY KEY (l_orderkey, l_linenumber)
      COMMENT = 'One row per product line inside an order',
    part AS CORTEX_DEMO_DB.TPCH_ANALYST.PART
      PRIMARY KEY (p_partkey)
      WITH SYNONYMS = ('products', 'items')
      COMMENT = 'Product catalog'
  )
  RELATIONSHIPS (
    lineitem_to_orders AS lineitem (l_orderkey) REFERENCES orders,
    lineitem_to_part   AS lineitem (l_partkey)  REFERENCES part
  )
  FACTS (
    lineitem.quantity    AS l_quantity,
    lineitem.net_revenue AS l_extendedprice * (1 - l_discount)
      COMMENT = 'Line revenue after discount',
    orders.order_total   AS o_totalprice
  )
  DIMENSIONS (
    orders.order_date     AS o_orderdate WITH SYNONYMS = ('purchase date'),
    orders.order_year     AS YEAR(o_orderdate),
    orders.order_status   AS o_orderstatus
      COMMENT = 'F = fulfilled, O = open, P = partially fulfilled',
    orders.order_priority AS o_orderpriority,
    part.product_name     AS p_name WITH SYNONYMS = ('product', 'part name'),
    part.brand            AS p_brand,
    lineitem.ship_mode    AS l_shipmode
  )
  METRICS (
    orders.order_count         AS COUNT(o_orderkey),
    orders.average_order_value AS AVG(orders.order_total),
    lineitem.total_quantity    AS SUM(lineitem.quantity),
    lineitem.total_revenue     AS SUM(lineitem.net_revenue)
      WITH SYNONYMS = ('sales', 'revenue')
  )
  COMMENT = 'Orders, order lines and products (TPC-H). Use for sales and product questions.'
  AI_SQL_GENERATION 'Round currency values to 2 decimals. Treat "sales" as total_revenue.'
  AI_VERIFIED_QUERIES (
    most_popular_product AS (
      QUESTION 'What is the most popular product sold?'
      ONBOARDING_QUESTION TRUE
      SQL 'SELECT p.product_name, SUM(l.quantity) AS total_quantity
           FROM lineitem AS l
           JOIN part AS p ON l.l_partkey = p.p_partkey
           GROUP BY p.product_name
           ORDER BY total_quantity DESC NULLS LAST
           LIMIT 1'
    )
  );

What each clause does

TABLES

Logical tables and their primary keys. Synonyms and comments help Cortex Analyst match business words.

RELATIONSHIPS

The joins. LINEITEM is the many side and references ORDERS and PART.

FACTS

Row-level values, such as quantity or net revenue.

DIMENSIONS

Fields people group or filter by, such as order year or product name.

METRICS

Aggregations people ask for, such as total revenue or order count.

AI_SQL_GENERATION

Custom instructions that guide how Cortex Analyst writes SQL.

AI_VERIFIED_QUERIES

Example questions with their correct SQL. ONBOARDING_QUESTION TRUE also suggests the question to new users.

Clause order matters. FACTS must come before DIMENSIONS, and the AI clauses come after COMMENT.

A2Validate the view

SHOW SEMANTIC VIEWS IN SCHEMA CORTEX_DEMO_DB.TPCH_ANALYST;
DESCRIBE SEMANTIC VIEW TPCH_SALES_SV;

DESCRIBE lists every table, relationship, fact, dimension and metric, so you can check the names before anyone asks a question.

A3Query it with SQL

Use the SEMANTIC_VIEW() clause and name the dimensions and metrics you want:

SELECT * FROM SEMANTIC_VIEW(
    TPCH_SALES_SV
    DIMENSIONS orders.order_year
    METRICS lineitem.total_revenue, orders.order_count
  )
ORDER BY order_year;

Or query it like a regular view and wrap each metric in AGG():

SELECT order_year, AGG(total_revenue) AS total_revenue
FROM TPCH_SALES_SV
GROUP BY order_year
ORDER BY order_year;

A4Ask Cortex Analyst through the REST API

Send the question in plain English. Replace the token with a programmatic access token for a user who can use the view.

curl -X POST "https://<account_identifier>.snowflakecomputing.com/api/v2/cortex/analyst/message" \
  -H "Authorization: Bearer <PROGRAMMATIC_ACCESS_TOKEN>" \
  -H "X-Snowflake-Authorization-Token-Type: PROGRAMMATIC_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "messages": [{"role": "user",
          "content": [{"type": "text", "text": "What is the most popular product sold?"}]}],
        "semantic_view": "CORTEX_DEMO_DB.TPCH_ANALYST.TPCH_SALES_SV"
      }'

The response contains Cortex Analyst’s interpretation of the question and the SQL it generated. Your application runs that SQL on a warehouse and shows the result.

A5Share with business users

Give business users access to the view, not to the tables behind it.

USE ROLE SYSADMIN;
GRANT USAGE ON DATABASE CORTEX_DEMO_DB TO ROLE <business_role>;
GRANT USAGE ON SCHEMA CORTEX_DEMO_DB.TPCH_ANALYST TO ROLE <business_role>;
GRANT USAGE ON WAREHOUSE CORTEX_WH TO ROLE <business_role>;

USE ROLE CORTEX_ANALYST_ROLE;
GRANT SELECT ON SEMANTIC VIEW CORTEX_DEMO_DB.TPCH_ANALYST.TPCH_SALES_SV TO ROLE <business_role>;

-- Path B view (skip if you only built Path A)
GRANT SELECT ON SEMANTIC VIEW CORTEX_DEMO_DB.TPCH_ANALYST.TPCH_SALES_GUI_SV TO ROLE <business_role>;

A role that does not own the view needs only SELECT on the semantic view, not on the base tables. Business users also need the SNOWFLAKE.CORTEX_USER database role, which PUBLIC has by default, and a warehouse to run the generated SQL.

A6Export the definition for Git or CI/CD

SELECT GET_DDL('SEMANTIC_VIEW', 'CORTEX_DEMO_DB.TPCH_ANALYST.TPCH_SALES_SV', TRUE);
SELECT SYSTEM$READ_YAML_FROM_SEMANTIC_VIEW('CORTEX_DEMO_DB.TPCH_ANALYST.TPCH_SALES_SV');

Store the DDL or YAML in your repository. When you redeploy, use CREATE OR ALTER SEMANTIC VIEW (or add COPY GRANTS) so existing grants are kept.

B1Open the wizard

1. Open your user menu at the bottom left of Snowsight, select Switch role, and choose CORTEX_ANALYST_ROLE.
2. In the left navigation, select AI & ML›Cortex Analyst. This page lists the semantic views you can access.
3. Click the arrow next to Create in Workspaces, then select Create in Cortex Analyst. This opens the classic wizard shown on this page.
4. At the top right of the wizard, check that the role is CORTEX_ANALYST_ROLE and the warehouse is CORTEX_WH.

Older Snowsight menus. If your account shows AI & ML›Studio instead, click Try on the Cortex Analyst card. In the Select a semantic model dialog, check the role and warehouse, select Semantic Views, then click + Create new.

B2Getting started

• Location to store: CORTEX_DEMO_DB.TPCH_ANALYST
• Name: TPCH_SALES_GUI_SV
• Description: say which questions the view answers, for example “Orders, order lines and products. Use for sales and product questions.”
• Click Next: Select tables at the bottom right.

B3Select tables

• On the All tab, expand CORTEX_DEMO_DB›TPCH_ANALYST and tick ORDERS, LINEITEM and PART.
• Open the Selected tab and check that it shows 3.
• Click Next: Select columns at the bottom right.

Keep your first view small. Snowflake recommends fewer than 10 tables for a first semantic view.

B4Select columns

• Click Expand all at the top right of the list to see every column.
• Untick columns nobody asks about, such as O_COMMENT and O_CLERK.
• Leave Include example data from selected columns to improve its quality ticked.
• Click Create and Save at the bottom right. Snowflake drafts dimensions, facts, descriptions and synonyms for you.

Snowflake recommends no more than 50 columns, and sample values improve accuracy. An LLM writes the drafts for each selected column, which is one more reason to keep the list focused.

B5Fix business names, descriptions and synonyms

1. In the left pane, scroll to Logical tables, expand ORDERS›Dimensions and click O_ORDERSTATUS.
2. In the Edit dimension panel, set:
   • Dimension name: order_status
   • Dimension description: F = fulfilled, O = open, P = partially fulfilled
   • Synonyms: keep only words your users really say
   Then click Save at the bottom right.
3. To add a metric, click + next to Metrics under LINEITEM. Name it total_revenue with the expression SUM(L_EXTENDEDPRICE * (1 - L_DISCOUNT)).
4. To add business rules, click Edit next to Custom Instructions at the top of the left pane, for example “Round currency values to 2 decimals.”

Write synonyms by hand. Use your internal terms and abbreviations. Auto-generated synonyms often lower answer quality, and the list in the screenshot is a good example of what to trim.

B6Add relationships

1. Scroll the left pane to Relationships and click + at the right of the heading.
2. Fill in the Add relationship form:
   • Relationship name: lineitem_to_orders
   • Join type: left outer. Relationship type: many to one
   • Left table: LINEITEM. Right table: ORDERS
   • Left column: L_ORDERKEY. Right column: O_ORDERKEY
3. Click Add, then repeat for lineitem_to_part, joining L_PARTKEY to P_PARTKEY.

Key columns missing from the lists? Set the primary key first: click Edit next to the ORDERS logical table and choose O_ORDERKEY (P_PARTKEY for PART). In the newer Semantic Studio editor, join and relationship types are usually inferred from the data and primary keys, so you don’t pick them.

B7Test, rate and save a verified query

1. In the chat panel on the right, type What is the most popular product sold? in Enter prompt and click Run.
2. Check the interpretation (“This is our interpretation of your question”), the result table, and the SQL on the Physical query and Semantic query tabs.

3. Rate the answer with the thumbs up or thumbs down icon next to Request ID. Add an optional comment and click Submit.
4. Save the question and its correct SQL as a verified query: click + next to Verified Queries in the left pane.
5. Click Save at the top right. Do this after every change.

6. Open the Monitoring tab (top left, next to Semantic Model) to review each question with its user, feedback and timestamp. Click a row to see the full conversation. New feedback shows up after a short delay.

B8See the SQL behind your GUI-built view

• In Catalog, browse to CORTEX_DEMO_DB›TPCH_ANALYST›Semantic Views›TPCH_SALES_GUI_SV.
• The Semantic View Details tab shows the full create or replace semantic view statement. Copy it into your repository if you want to manage the view with SQL from now on (see A6).
• To open a worksheet on the view, use the ... menu at the top right, then Query with SQL.

NewNewer option: Workspaces and Semantic View Autopilot

• In Workspaces, select Add new›Semantic View to open Semantic View Autopilot. You can start with CoCo, Snowflake’s AI agent (recommended), or from SQL queries, a Tableau file, a Power BI file or a YAML file.
• The flow mirrors B2 to B4: location, name and description, then context, Select tables, Select columns, sample values and AI descriptions, then Create and save and Save and run.
• Example SQL queries you add become verified queries automatically.
• Refine the view in Semantic Studio, then click Deploy in the top bar, choose the target, review the differences and confirm.