What you will be able to do
- Explain how Cortex Analyst uses semantic views to turn natural language into SQL, and where Cortex Search fits
- Write verified queries, configure onboarding (suggested) questions and add custom instructions
- Choose a Cortex model by trading latency, capability and cost for a given task
- Apply the documented levers for accuracy and hallucination reduction
- Decide when Provisioned Throughput is needed and how it is reserved and used
1.Cortex Analyst: text-to-SQL over semantic views
For structured data, the main managed service is Cortex Analyst. Business users ask questions in natural language, and Cortex Analyst generates SQL that runs on your own warehouse. It is a REST API, so you can embed it in Streamlit, Slack, Teams or a custom chat UI. At runtime it chooses the combination of models itself, so there is no model to pick and no GPU capacity to plan.
Accuracy depends on the semantic layer. A database schema alone does not tell an LLM how the business defines its metrics. Semantic views add that layer: logical tables, dimensions, facts, metrics, relationships, synonyms and verified examples. They are the recommended approach. Legacy YAML semantic models on a stage still work for backward compatibility. Generated SQL follows RBAC, so users see only the data their role allows.
Integration with Cortex Search. A semantic model can reference Cortex Search services, and a role that calls Cortex Analyst needs USAGE on those services in addition to SELECT on the tables. The sources available for this lesson document only that privilege requirement. They do not describe how Analyst uses the search service, for example for matching literal values, so that mechanism is not covered here.
AI_COMPLETE on structured data is a different pattern. Cortex AI Functions run row by row over table columns inside SQL, and they are tuned for batch throughput over large tables, not for interactive questions.
Checkpoint 1 of 7· Check yourself
A role can call Cortex Analyst and has SELECT on every table in the semantic model, but queries fail for questions that use a Cortex Search service referenced in the model. What is missing?
Using Cortex Analyst with a semantic model requires SELECT on the referenced tables and USAGE on any Cortex Search services the model mentions.
“The Cortex Search services mentioned in the semantic model.”Source: docs.snowflake.com
2.Verified Query Repository, suggested questions and custom instructions
The Verified Query Repository (VQR) is a set of question-and-SQL pairs that you have checked. When a user asks something similar, Cortex Analyst bases its SQL on the matching verified query, and the confidence field of the API response shows which one it used. Verified SQL must use the semantic model's logical table and column names, with logical tables prefixed by two underscores, as in __sales_data below. It must not use the physical names. An incorrect verified query makes Cortex Analyst's accuracy worse.
verified_queries:
- name: "California profit"
question: "What was the profit from California last month?"
verified_at: 1714497970
verified_by: Jane Doe
use_as_onboarding_question: true
sql: "
SELECT sum(profit)
FROM __sales_data
WHERE state = 'CA'
AND sale_timestamp >= DATE_TRUNC('month', DATEADD('month', -1, CURRENT_DATE))
AND sale_timestamp < DATE_TRUNC('month', CURRENT_DATE)
"Suggested (onboarding) questions come from one of three modes, depending on how the model is set up:
1. No VQR: an LLM generates up to three suggestions, and they may not be answerable.
2. VQR present: up to five VQR questions, chosen by similarity to what the user typed.
3. **Questions flagged use_as_onboarding_question: true**: every flagged question is returned whatever the user typed, even if there are more than five.
Snowsight can also suggest new verified queries based on real usage. They sit in a queue for a person to accept, edit or dismiss, and nothing is applied automatically.
Custom instructions guide Analyst in plain language. On a semantic view, AI_SQL_GENERATION controls how SQL is written (for example, "round numeric columns to 2 decimals"). AI_QUESTION_CATEGORIZATION controls how questions are handled, for example rejecting certain topics or treating a question as UNCLEAR and asking the user for a missing filter. In SQL, verified queries go in an AI_VERIFIED_QUERIES clause:
Checkpoint 2 of 7· Fill the gap
Which clause marks a verified query as one to suggest to users of a Cortex Analyst app?
AI_VERIFIED_QUERIES (
<verified_query_name> AS (
QUESTION '<question>'
VERIFIED_AT <timestamp>
? <boolean>
VERIFIED_BY '( <purpose> = <contact> )'
SQL '<verified_query>'
)
[ , ... ]
)In CREATE SEMANTIC VIEW, ONBOARDING_QUESTION TRUE plays the same role as use_as_onboarding_question in YAML. AI_SQL_GENERATION and AI_QUESTION_CATEGORIZATION are custom-instruction clauses, not parts of a verified query.
Source: docs.snowflake.com3.Choosing a model: latency, capability and cost
When you call AI_COMPLETE yourself, the model is your decision. The models differ in capability, latency and cost, and the rule is to match the model to the size and complexity of the task. If you don't know where to start, set a quality baseline with the most capable models and then test smaller ones against it. Simple, high-volume or latency-sensitive tasks such as classification, short summaries and simple Q&A belong on small, fast models. Multi-step reasoning, agentic work and multimodal input need the larger models.
| Model | Documented positioning | Context window |
|---|---|---|
| claude-opus-5 | Among the most capable; long-horizon agentic work, large document collections | 1,000,000 tokens |
| claude-sonnet-4-6 | Leader in general reasoning and multimodal capabilities; agentic workflows | Large; see model reference |
| claude-haiku-4-5 | Fast, cost-efficient; low-latency, high-throughput; simple classification and summarization | 200,000 tokens |
| llama3.1-8b | Light-weight, ultra-fast; low to moderate reasoning | 128K |
| mistral-7b | Simplest summarization, structuring and Q&A done quickly | 32K |
Benchmarks show the capability side of the trade-off. On MMLU, llama3.1-70b scores 86, llama3.1-8b scores 73 and mistral-7b scores 62.5. A larger model buys more reasoning at higher latency and cost. Context limits also matter: input over the context window causes an error, and output past the limit is truncated. How you call the model affects latency too. AI Functions in SQL are optimized for throughput on batches, and Snowflake recommends the REST API for interactive, latency-sensitive use.
Checkpoint 3 of 7· Check yourself
An interactive app must label each incoming message with one of five categories in well under a second. Which approach does the model reference support?
Simple classification where speed matters suits a small, fast model, and the REST API is the recommended path when latency matters. A nightly batch does not meet an interactive requirement.
“well-suited for simple summarization, classification, and question-answering tasks where speed and cost matter more than top-tier reasoning”Source: docs.snowflake.com
Checkpoint 4 of 7· Exam question
A finance team wants to pull the invoice number, total amount, and due date from thousands of vendor invoices in various formats into a structured table with defined columns. Which function is purpose-built for this?
Correct answer: A — AI_EXTRACT
- A. This function performs schema-based structured extraction of named fields such as invoice number, amount, and due date directly from documents, tables, checkboxes, and handwriting, matching the defined output shape the finance team needs.
- B. This function converts documents into rich text or layout-preserving text; it does not natively map content into a user-defined structured schema of specific fields.
- C. This function computes semantic relatedness between two inputs and returns a similarity score; it does not extract structured fields from documents.
- D. This function returns a boolean for filtering rows or text based on a condition; it is not designed to extract structured field values from documents.
4.Accuracy levers: grounding, verified examples and fine-tuning
Hallucination happens when a model answers from its training rather than from your data. The documented fix is to ground each answer in retrieved content. Cortex Search supplies an LLM with current proprietary context, and well-sized chunks give the model more relevant text. For text-to-SQL, the equivalent levers are semantic views, which carry business definitions and join paths, the VQR, which supplies verified examples, and custom instructions.
Fine-tuning: the sources for this lesson do not describe a general Cortex fine-tuning feature. The only training guidance they contain is for AI_EXTRACT table extraction. There, training on the specified column set might improve results, and a fine-tuning dataset should leave out rows with no answer. For anything beyond that, see the Snowflake documentation.
Checkpoint 5 of 7· Check yourself
A Cortex Analyst app keeps calculating 'net revenue' differently from the finance team's definition. Which change targets this most directly?
Cortex Analyst picks its models itself. Its accuracy comes from the semantic layer and from verified question-and-SQL pairs that it reuses for similar questions.
“providing a collection of questions and corresponding SQL queries to answer them”Source: docs.snowflake.com
5.Provisioned Throughput: reserved capacity for predictable latency
By default, Cortex inference is serverless and on demand. Provisioned Throughput (PT) reserves dedicated inference capacity, sized in provisioned throughput units (PTUs), for a one-month term. You use it in REST API calls when you need a consistent end-user experience. It is available on AWS and Azure for a fixed list of models, each with a minimum PTU count and an increment: Llama 3.1-8B starts at 64 PTUs and grows in steps of 32, and Llama 3.1-405B starts at 512. A PT is a schema-level object. By default only ACCOUNTADMIN can create one, and callers need USAGE on the PT ID. It does not renew automatically.
CREATE PROVISIONED THROUGHPUT my_pt CLOUD_PROVIDER='aws', MODEL='llama3.1-8B', PTUS=64, TERM_START='2025-04-15' TERM_END='2025-05-15'Checkpoint 6 of 7· Put it in order
Put the steps for putting Provisioned Throughput into use in order
- 1.Run CREATE PROVISIONED THROUGHPUT and note the PT ID in the response
- 2.Open a Snowflake Support ticket with your account identifier and the PT ID
- 3.Pass the PT ID in your AI_COMPLETE REST API calls
- 4.Check DESCRIBE PROVISIONED THROUGHPUT until the state is ACTIVE
Creating the PT only requests capacity. Support enables it, it moves from REQUESTED through APPROVED to ACTIVE, and only then can REST calls use it. Using a PT does not change how the API behaves.
“After the PT is in the ACTIVE state, you can use it in your AI_COMPLETE REST API calls.”Source: docs.snowflake.com
Checkpoint 7 of 7· Exam question
Which Snowflake Cortex function computes a semantic relatedness score between two text inputs by comparing their embedding vectors?
Correct answer: A — AI_SIMILARITY
- A. This function generates embeddings internally for the two supplied inputs and returns a numeric measure of semantic relatedness, which is exactly a similarity score between two text (or image) inputs.
- B. This function assigns one or more predefined category labels to an input rather than producing a pairwise similarity score.
- C. This function pulls structured field values out of unstructured content and does not return a semantic relatedness score.
- D. This function generates free-text or structured completions from an LLM and is not designed to output a similarity score between two inputs.
Sources10
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.Verified queries should use the physical table and column names, because that is the SQL that actually runs.Why is that wrong?
Verified SQL must use the semantic model's logical table and column names, with logical tables prefixed by two underscores.
Covered in Verified Query Repository, suggested questions and custom instructions
2.Without a VQR, Cortex Analyst shows no suggested questions.Why is that wrong?
Without a VQR, an LLM still generates up to three suggestions, though they may not be answerable. With a VQR, up to five verified questions are returned.
Covered in Verified Query Repository, suggested questions and custom instructions
3.Provisioned Throughput is billed per token like normal serverless inference and renews each month.Why is that wrong?
You pay for the allocated PTUs for the whole one-month term whatever you use, and the reservation does not renew automatically.
Covered in Provisioned Throughput: reserved capacity for predictable latency
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“At runtime, Cortex Analyst selects the best combination of models to ensure the highest accuracy and performance for each query.”
↩︎ Cortex Analyst: text-to-SQL over semantic views“Semantic Views are the recommended approach for working with Cortex Analyst”
↩︎ Cortex Analyst: text-to-SQL over semantic views“Legacy semantic model YAML files (stored on stages) are still supported for backward compatibility”
↩︎ Cortex Analyst: text-to-SQL over semantic views“The Cortex Search services mentioned in the semantic model.”
↩︎ Checkpoint - 2.
“We recommend using these functions to process numerous inputs such as text from large SQL tables.”
↩︎ Cortex Analyst: text-to-SQL over semantic views“For more interactive use cases where latency is important, use the REST API.”
↩︎ Choosing a model: latency, capability and cost - 3.
“Invalid or inaccurate queries can negatively impact Cortex Analyst’s performance and accuracy.”
↩︎ Verified Query Repository, suggested questions and custom instructions“Verified SQL queries must use the names of the logical tables and columns defined in the semantic model”
↩︎ Exam trap 1“providing a collection of questions and corresponding SQL queries to answer them”
↩︎ Checkpoint - 4.https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-analyst/suggested-questions-featureOfficial docs
“Cortex Analyst returns all questions marked as onboarding questions, regardless of their similarity to the user’s input.”
↩︎ Verified Query Repository, suggested questions and custom instructions“Cortex Analyst uses the underlying Large Language Models (LLMs) to generate up to three suggested questions.”
↩︎ Exam trap 2 - 5.
“For instructions on how to generate the SQL statement, use the AI_SQL_GENERATION clause in the CREATE SEMANTIC VIEW command.”
↩︎ Verified Query Repository, suggested questions and custom instructions - 6.
“Suggestions are not automatically applied.”
↩︎ Verified Query Repository, suggested questions and custom instructions - 7.
“To achieve the best performance per credit, choose a model that’s a good match for the content size and complexity of your task.”
↩︎ Choosing a model: latency, capability and cost“try the most capable models first to establish a baseline to evaluate other models”
↩︎ Choosing a model: latency, capability and cost“Inputs exceeding the context window limit result in an error. Output that exceeds the context window limit is truncated.”
↩︎ Choosing a model: latency, capability and cost“well-suited for simple summarization, classification, and question-answering tasks where speed and cost matter more than top-tier reasoning”
↩︎ Checkpoint - 8.https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-search/cortex-search-overviewOfficial docs
“return answers that are grounded in your most up-to-date proprietary data”
↩︎ Accuracy levers: grounding, verified examples and fine-tuning - 9.
“When you create a fine-tuning dataset, skip the rows with no answer”
↩︎ Accuracy levers: grounding, verified examples and fine-tuning“Note that training on the specified column set might improve the results.”
↩︎ Accuracy levers: grounding, verified examples and fine-tuning - 10.
“Cortex allocates the required capacity for a one-month term”
↩︎ Provisioned Throughput: reserved capacity for predictable latency“You can use the PTUs in your REST API calls for a consistent end-user experience.”
↩︎ Provisioned Throughput: reserved capacity for predictable latency“By default, ACCOUNTADMIN is the only role that can create the provisioned throughput.”
↩︎ Provisioned Throughput: reserved capacity for predictable latency“Provisioned Throughput does not renew automatically.”
↩︎ Exam trap 3“You incur charges for the allocated PTUs regardless of your actual usage during the term.”
↩︎ Prediction“After the PT is in the ACTIVE state, you can use it in your AI_COMPLETE REST API calls.”
↩︎ Checkpoint