How to Set Up Snowflake Cortex Analyst

Snowflake Cortex Analyst converts plain-English business questions into SQL and runs them against your Snowflake tables, returning results without requiring users to write a single query. Getting it working requires three things: the right Snowflake roles, a semantic model YAML file that maps your business terminology to your table schema, and an application layer to surface the interface. This guide walks through each step.

What Snowflake Cortex Analyst Does

Cortex Analyst is a managed Snowflake service that turns natural language into SQL. When a business user asks "Which regions had the lowest margin last quarter?", Cortex Analyst parses the question, generates the appropriate SQL, runs it against your tables, and returns both the result and the SQL it used. Users interact through a chat interface and never need to open a query editor.

The component that makes this work is the semantic model: a YAML file you create once that describes your tables, column meanings, business metrics, and relationships. The LLM does not operate directly against your raw schema. It interprets questions through the semantic model, which bridges the gap between how business users phrase questions ("total revenue") and how data is stored ("SUM of AMOUNT from the orders table where status is not cancelled").

A well-written semantic model produces accurate responses. A poorly written one produces plausible-looking SQL that answers the wrong question. Most of the work in this setup is in the semantic model, not in the Snowflake configuration.

According to Snowflake's developer documentation, Cortex Analyst is available in generally available status as of early 2025 and is charged per message processed on successful HTTP 200 responses, with SQL execution billed separately through standard warehouse compute.

Prerequisites

Confirm each of these before starting:

Supported region. Cortex Analyst runs natively in AWS regions (Virginia, Oregon, Tokyo, Sydney, Frankfurt, Ireland) and Azure (East US 2, West Europe). Accounts in other regions can route queries through cross-region inference, which must be enabled in account settings under AI and ML.

Role permissions. The role creating the semantic model needs CREATE STAGE privileges and READ or WRITE access to stages. The role querying Cortex Analyst needs the SNOWFLAKE.CORTEX_USER or SNOWFLAKE.CORTEX_ANALYST_USER database role. Snowflake grants SNOWFLAKE.CORTEX_USER to PUBLIC by default. Verify:

SHOW GRANTS TO ROLE PUBLIC;

Tables already in Snowflake. The tables Cortex Analyst will query must already be loaded. The service does not have access to external data sources unless they are registered as external tables inside Snowflake.

Step 1: Prepare Your Tables

Cortex Analyst works against standard Snowflake tables or views. For this guide, a simple sales schema with two tables:

CREATE DATABASE sales_db;
CREATE SCHEMA sales_db.core;

CREATE OR REPLACE TABLE sales_db.core.orders (
  order_id    NUMBER PRIMARY KEY,
  customer_id NUMBER,
  product_id  NUMBER,
  amount      FLOAT,
  order_date  DATE,
  region      VARCHAR
);

CREATE OR REPLACE TABLE sales_db.core.products (
  product_id   NUMBER PRIMARY KEY,
  product_name VARCHAR,
  category     VARCHAR,
  unit_price   FLOAT
);

Column names should be descriptive. Cortex Analyst reads column names as part of its interpretation. A column named amt is harder to map correctly than one named order_amount.

Step 2: Write the Semantic Model YAML

The semantic model is the core configuration file. Create sales_model.yaml:

name: Sales Analytics Model
description: Revenue and order data for the sales team.

tables:
  - name: orders
    base_table:
      database: SALES_DB
      schema: CORE
      table: ORDERS
    description: One row per customer order.
    primary_key:
      columns:
        - ORDER_ID
    dimensions:
      - name: region
        expr: REGION
        description: Geographic region of the order. Values include APAC, EMEA, and AMER.
        data_type: VARCHAR
      - name: order_date
        expr: ORDER_DATE
        description: Date the order was placed.
        data_type: DATE
      - name: customer_id
        expr: CUSTOMER_ID
        description: Unique identifier for the customer. Not a metric; do not aggregate.
        data_type: NUMBER
    measures:
      - name: total_revenue
        expr: AMOUNT
        description: Order value in USD. Use SUM for revenue aggregation.
        data_type: FLOAT
        default_aggregation: SUM

  - name: products
    base_table:
      database: SALES_DB
      schema: CORE
      table: PRODUCTS
    description: Product catalog with pricing and category.
    primary_key:
      columns:
        - PRODUCT_ID
    dimensions:
      - name: product_name
        expr: PRODUCT_NAME
        description: Human-readable product name.
        data_type: VARCHAR
      - name: category
        expr: CATEGORY
        description: Product category such as Electronics, Apparel, or Furniture.
        data_type: VARCHAR
    measures:
      - name: unit_price
        expr: UNIT_PRICE
        description: List price per unit in USD.
        data_type: FLOAT
        default_aggregation: AVG

relationships:
  - name: orders_to_products
    left_table: orders
    right_table: products
    relationship_type: MANY_TO_ONE
    relationship_columns:
      - left_column: PRODUCT_ID
        right_column: PRODUCT_ID

Three rules that reduce errors in practice:

Column names in expr fields must match the actual Snowflake column names exactly. The YAML is case-insensitive in Snowflake, but spelling must be correct.

Numeric identifier columns belong in dimensions, not measures. Cortex Analyst will attempt to aggregate a column if it appears under measures. Always classify ID columns as dimensions with a note in the description that they are identifiers, not metrics. The Snowflake Semantic Model Generator tool sometimes misclassifies these automatically.

The description fields are read by the LLM. Write them as you would explain the column to a new analyst: precise, unambiguous, in the business language your users would recognize. Short but specific descriptions outperform long vague ones.

You can optionally add verified_queries blocks to the YAML. These pair a natural language question with its correct SQL. Adding five to ten verified queries for your most frequent questions significantly improves accuracy because the LLM uses them as reference answers rather than regenerating SQL each time.

Step 3: Upload the YAML to a Snowflake Stage

Create a stage and upload the file:

CREATE STAGE sales_db.core.semantic_models
  DIRECTORY = (ENABLE = TRUE);

Upload using SnowSQL:

PUT file:///path/to/sales_model.yaml @sales_db.core.semantic_models AUTO_COMPRESS=FALSE;

Or use Snowsight's file upload interface: navigate to Data, then Databases, select the stage, and click Upload.

Verify the file is staged:

LIST @sales_db.core.semantic_models;

The path used in API calls will be @sales_db.core.semantic_models/sales_model.yaml.

Step 4: Call the Cortex Analyst REST API

Cortex Analyst is accessed via a REST endpoint. Below is a Python example:

import requests
import json

ACCOUNT = "yourorg-youraccountname"
TOKEN = "your_session_token"

url = f"https://{ACCOUNT}.snowflakecomputing.com/api/v2/cortex/analyst/message"

headers = {
    "Authorization": f'Snowflake Token="{TOKEN}"',
    "Content-Type": "application/json",
    "X-Snowflake-Authorization-Token-Type": "KEYPAIR_JWT"
}

payload = {
    "messages": [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What were the top 5 products by revenue last quarter?"}
            ]
        }
    ],
    "semantic_model_file": "@sales_db.core.semantic_models/sales_model.yaml"
}

response = requests.post(url, headers=headers, json=payload)
print(json.dumps(response.json(), indent=2))

The response contains the generated SQL, the plain-English answer, and optional follow-up question suggestions. For multi-turn conversations, pass the full conversation history in the messages array. Note that Cortex Analyst does not retain the results of previous SQL queries across turns; it can reference what was asked but not the data that was returned.

Step 5: Build a Front End for Business Users

For non-technical users, wrap the API in a simple chat interface. Snowflake provides a Streamlit-in-Snowflake Quickstart template that connects to Cortex Analyst and renders a working chat UI without building anything custom from scratch.

For teams that want natural language analytics without a Snowflake account or a semantic model to maintain, VSLZ AI handles this from a plain file upload with no configuration required.

Common Setup Problems

"I cannot answer this question." The question uses business terms not defined in the semantic model. Add or expand the description for the relevant dimension or measure.

Numeric IDs are being summed or averaged. The column is classified under measures. Move it to dimensions and add a note in the description that it is an identifier, not a metric.

Cross-region inference error. The Snowflake account is in a region not on the native support list. Enable cross-region inference in account settings under AI and ML.

Inconsistent answers to the same question. Add verified_queries for your high-frequency questions. Verified queries lock in the correct SQL so the LLM does not regenerate it each time, which reduces variance.

Costs are higher than expected. Each successful response is billed. Add verified queries for common questions, which short-circuits LLM inference on predictable queries and lowers per-question cost.

Summary

The setup has three core steps: prepare your tables, write the semantic model YAML, and connect the REST API to a front end. The semantic model is where nearly all of the work lives. Columns with precise descriptions, identifiers correctly classified as dimensions, explicit join definitions, and a set of verified queries produce a system that handles the majority of routine business questions accurately. Start with one business domain, test with real questions before sharing with users, and expand the semantic model based on what users actually ask.