Snowflake for Gen AI · Topic 3 of 13

Cortex Analyst and Text-to-SQL Use Cases

What Cortex Analyst is, how it turns business questions into SQL using semantic views, its access roles and limits, and the text-to-SQL cases that fit.

  • 4 min
In a nutshell
  • Cortex Analyst = natural language to SQL over structured data, delivered by REST API.
  • Semantic views are recommended; YAML on a stage is legacy.
  • Endpoint: /api/v2/cortex/analyst/message; one data source per request.

What it is

Cortex Analyst is a managed, LLM powered feature that turns a business question in plain language into SQL and runs it against structured data in Snowflake. It is exposed as a REST API, so you embed it in a Streamlit app, Slack, Teams or any custom chat interface.

It does not guess your business meaning. It reads a semantic layer that you define (a semantic view, or the older semantic model YAML file) so that "revenue" or "active customer" always means the same thing.

Business questionCortex AnalystREST APIreadsSemantic viewbusiness definitionswritesSQLrun in your warehouseAnswertable or chart

Snowflake recommends moving to Cortex Agents, which support every Cortex Analyst capability. In an agent, Cortex Analyst is simply one of the tools.

How it works

The semantic layer

OptionWhere it livesStatus
Semantic viewSchema level object with logical tables, dimensions, facts, metrics and relationshipsRecommended; native RBAC and sharing
Semantic model YAMLFile on a stageLegacy; still supported, not recommended for new work

The semantic layer is what makes answers trustworthy. Without it, the model would guess join paths and column meanings from raw table names.

Access

In practice a team keeps the semantic view small and focused. Each view should describe one business area, such as sales or support, with clear names for dimensions and metrics. Questions that cross areas are better handled by an agent that holds several views as separate tools.

SNOWFLAKE.CORTEX_USER gives access to all covered AI features and is granted to PUBLIC by default. SNOWFLAKE.CORTEX_ANALYST_USER gives access to Cortex Analyst only. To limit a team to Analyst, revoke CORTEX_USER from the user roles and grant CORTEX_ANALYST_USER. The caller also needs SELECT on the underlying tables, and READ on the stage if a YAML file is used.

Calling it

The endpoint is POST /api/v2/cortex/analyst/message. The request body holds messages and exactly one data source: a semantic view, a semantic model file on a stage, or an inline semantic model. The response contains text, sql and, for ambiguous questions, suggestions.

Follow up questions work because the client sends the whole conversation in messages each time. Cortex Analyst keeps no state between calls, so long conversations cost more.

Exam tip

Cortex Analyst generates SQL and returns it. Your application, or an agent, runs the SQL. The warehouse cost of that run is separate from the per message Analyst cost.

Text-to-SQL use cases

Choose Cortex Analyst when the question can be answered by SQL over tables.

  • Self service analytics: a sales manager asks "revenue by region last quarter" without writing SQL.
  • Embedded analytics: a chat panel in an internal app answers metric questions from a governed view.
  • Metric consistency: the same definition of "margin" is used by every question.
  • Agent tool: an agent routes numeric questions to Analyst and document questions to Search.
Question typenumbers and trendsroute toCortex Analyststructured dataQuestion typepolicies and documentsroute toCortex Searchunstructured data

It is the wrong tool for open ended insight requests ("why did churn rise?") that SQL alone cannot resolve, and it cannot reference the results of earlier SQL queries. Long conversations or frequent topic changes can degrade follow up handling, so reset the conversation when the intent shifts.

Watch out

Cortex Analyst is natively available only in listed regions. Other regions use cross-region inference, covered later in this chapter.

Common mistakes

Pointing Analyst at raw tables without a semantic layer. Accuracy depends on the semantic view.

Granting CORTEX_USER when only Analyst is intended. CORTEX_ANALYST_USER is the narrow role.

Expecting the API to remember the conversation. The client resends history every turn.

Using it for documents. Unstructured text needs Cortex Search.

Forgetting table privileges. The role still needs SELECT on the tables the semantic layer reads.

What to remember for the exam

  • Cortex Analyst = natural language to SQL over structured data, delivered by REST API.
  • Semantic views are recommended; YAML on a stage is legacy.
  • Endpoint: /api/v2/cortex/analyst/message; one data source per request.
  • CORTEX_ANALYST_USER limits a role to Analyst only.
  • Cortex Agents are the recommended place to use Analyst going forward.
  • No memory between requests; send the history.

Check yourself

  • What does Cortex Analyst return to the caller?

    Interpreted text and the generated SQL, or suggestions when the question is ambiguous.

  • Which database role restricts access to Cortex Analyst only?

    SNOWFLAKE.CORTEX_ANALYST_USER.

  • Which question fits Search rather than Analyst?

    A question answered from policy documents, because that is unstructured text.

Topic 3 of 13 in Snowflake for Gen AI

Test yourself on Snowflake for Gen AI

The full Snowflake GES-C02 question bank has 585 questions, with timed practice exams and an explanation for every answer.

This study guide is independent and is not affiliated with, endorsed by, or sponsored by Snowflake. Vendor names, certification names and exam codes are trademarks of their respective owners and are used for identification only.