Cortex Analyst¶

Key Features¶

• Self-serve analytics via natural language queries. Delight your business teams and non-technical users with instant answers and insights from their structured data in Snowflake. Using Cortex Analyst, you can build downstream chat applications that allow your users to ask questions using natural language and receive accurate answers on the fly.

• Convenient REST API for integration into existing business workflows. Cortex Analyst takes an API-first approach, giving you full control over the end user experience. Easily integrate Cortex Analyst into existing business tools and platforms, bringing the power of data insights to where business users already operate, such as Streamlit apps, Slack, Teams, custom chat interfaces, and more.

• Powered by state-of-the-art large language models: By default, Cortex Analyst is powered by the latest Meta Llama and Mistral models, which run securely inside Snowflake Cortex, Snowflake’s intelligent, fully managed AI service. Optionally, you can also give Cortex Analyst access to the latest Azure-hosted OpenAI GPT models. At runtime, Cortex Analyst selects the best combination of models to ensure the highest accuracy and performance for each query. For details, see Enabling use of Azure OpenAI models. As LLMs evolve, Snowflake will continue to explore adding more models to the mix to further improve performance and accuracy.

• Semantic model for high precision and accuracy: Generic AI solutions often struggle with text-to-SQL conversions when given only a database schema, as schemas lack critical knowledge like business process definitions and metrics handling. Cortex Analyst overcomes this limitation by using a semantic model that bridges the gap between business users and databases. Captured in a lightweight YAML file, the overall structure and concepts of the semantic model are similar to those of database schemas, but allow for a richer description of the semantic information around the data.

• Security and governance. Snowflake’s privacy-first foundation and enterprise-grade security ensure that you can explore AI-driven use cases with confidence, knowing your data is protected by the highest standards of privacy and governance.

  • Cortex Analyst does not train on Customer Data. We do not use your Customer Data to train or fine-tune any Model to be made available for use across our customer base. Additionally, for inference, Cortex Analyst utilizes the metadata provided in the semantic model YAML file (e.g., table names, column names, value type, descriptions, etc.) only for SQL-query generation. This SQL query is then executed in your Snowflake virtual warehouse to generate the final output.

  • Data stays within Snowflake’s governance boundary. By default, Cortex Analyst is powered by Snowflake-hosted LLMs from Mistral and Meta, ensuring that no data, including metadata or prompts, leaves Snowflake’s governance boundary. If you opt to use Azure OpenAI models, only metadata and prompts are transmitted outside of Snowflake’s governance boundary.

  • Seamless integration with Snowflake’s Privacy and Governance features. Cortex Analyst fully integrates with Snowflake’s role-based access control (RBAC) policies, ensuring that SQL queries generated and executed adhere to all established access controls. This guarantees robust security and governance for your data.

Limiting access to specific roles¶

By default, the CORTEX_USER role is granted to the PUBLIC role. The PUBLIC role is automatically granted to all users and roles. If you don’t want all users to have this privilege, you can revoke access to the PUBLIC role and grant access to specific roles. For more information, see Required privileges.

To control access to specific semantic models, you can store the YAML file in a stage and control access to that stage.

Considerations¶

Semantic model files are classified as metadata. If you opt in to using Azure OpenAI models in Cortex Analyst, your semantic model will be processed by Microsoft Azure, a third party. Customer Data, however, is not shared with or processed by Azure.

ENABLE_CORTEX_ANALYST_MODEL_AZURE_OPENAI¶

The ENABLE_CORTEX_ANALYST_MODEL_AZURE_OPENAI account parameter, if TRUE, allows Cortex Analyst to use Azure OpenAI models.

Known limitations in multi-turn conversations¶

Some of the following limitations might be addressed in future versions of Cortex Analyst.

Access to the results of previous SQL queries

Cortex Analyst doesn’t have access to results from previous SQL queries. For example, if you first ask, “What are my products?” and then ask, “What is the revenue of the second product?”, Cortex Analyst cannot refer to the list of products from the first query to get the second product.

General business insights

Cortex Analyst is limited to answering questions that can be resolved with SQL. It does not generate insights for broader business-related queries, such as “What trends do you observe?”

Long conversations

If a conversation includes too many turns or the user shifts intent frequently, Cortex Analyst might struggle to interpret the follow-up questions. In such cases, reset the conversation and start again.

Create a semantic model¶

A semantic model is a lightweight mechanism that addresses issues related to the language difference between business users and database definitions by allowing for the specification of additional semantic details about a dataset. These additional semantic details, like more descriptive names or synonyms, enable Cortex Analyst to answer data questions much more reliably.

1. Start with a list of questions you would like Cortex Analyst to answer. Based on that, decide on the dataset for your semantic model.

2. Create your semantic model YAML based on the specification. For convenience, try the Semantic model generator. Also, be sure to review the tips for creating a semantic model.

Upload semantic model¶

You can upload a semantic model YAML file to a stage or pass the semantic model YAML as a string in the request body. If you upload a semantic model YAML to a stage, access to that semantic model is controlled by access to the stage it’s uploaded to. This means that any role with access to the stage can access the semantic models on that stage even if the role doesn’t have access to the tables that the models are based on. Ensure that roles granted access to a stage have SELECT access on all tables referenced in all semantic models on that stage.

Below is an example of how to set up the stages containing the semantic models. One stage (public) is accessible to all members of the organization, whereas another stage (sales) is only accessible to the sales_analyst role.

Create the database and schema for the stage. The following example creates a database named semantic_model with a schema named definition but you can use any valid identifier string for these names.

CREATE DATABASE semantic_model;
CREATE SCHEMA semantic_model.definitions;
GRANT USAGE ON DATABASE semantic_model TO ROLE PUBLIC;
GRANT USAGE ON SCHEMA semantic_model.definitions TO ROLE PUBLIC;

USE SCHEMA semantic_model.definitions;

Then create the stages for storing your semantic models:

CREATE STAGE public DIRECTORY = (ENABLE = TRUE);
GRANT READ ON STAGE public TO ROLE PUBLIC;

CREATE STAGE sales DIRECTORY = (ENABLE = TRUE);
GRANT READ ON STAGE sales TO ROLE sales_analyst;

If using Snowsight, you can refresh the page and find the newly created stages in the database object explorer. You can open the stage page in a new tab and upload your YAML files in Snowsight.

Alternatively, you can use the Snowflake CLI client to upload from your local file system.

snow stage copy file:///path/to/local/file.yaml @sales

Creating a Streamlit in Snowflake App¶

This example shows you how to create a Streamlit in Snowflake app that takes a natural language question as input and calls Cortex Analyst to generate an answer based on the semantic model you provide.

For more information on creating and running Streamlit apps in Snowflake, see About Streamlit in Snowflake.

1. Follow the directions in Create a Streamlit app by using Snowsight to create a new Streamlit app in Snowsight.

2. Copy the Streamlit code from our GitHub repo into the code editor.

3. Replace the placeholder values with your account details.

4. To preview the app, select Run to update the content in the Streamlit preview pane.

Interact with the Streamlit App¶

1. Navigate to the Streamlit app in your browser or the Streamlit in Snowflake preview pane.

2. Start asking questions about your data in natural language (e.g. “What questions can I ask?”).

Create a standalone Streamlit app¶

You can also use the example code to build a standalone app.

1. Install Streamlit.

2. Create a Python file locally called analyst_api.py.

3. Copy the Streamlit code from our GitHub repo into the file.

4. Replace the placeholder values with your account details.

5. Run the Streamlit app using streamlit run analyst_api.py.

The database and schema specified in the code is the stage location for the semantic model YAML file. The role used in the Snowflake connector should have access to underlying data defined in semantic model.

For a more comprehensive implementation, see the Cortex Analyst advanced SiS demo in the Snowflake Samples GitHub repository. This repository is configured with various pre-built features that make deploying Cortex Analyst seamless and robust.