Cortex chat apps: privileges and multi-turn COMPLETE calls

1.Setting up access: one privilege plus one database role

Before you write any chat code, the role your application runs as must be allowed to call Cortex. Access depends on two separate things, and you need both. The first is the account-level privilege USE AI FUNCTIONS, or a per-function privilege such as USE AI FUNCTION AI_COMPLETE. The second is one of the database roles in the SNOWFLAKE database, either CORTEX_USER or AI_FUNCTIONS_USER. Having only one of the two is a common reason a new chat app fails on its first call.

The defaults are permissive. USE AI FUNCTIONS is granted to PUBLIC by default, and so is CORTEX_USER. Because every user and role gets PUBLIC, a new account can usually call Cortex functions straight away. To lock this down, an administrator revokes the grants from PUBLIC and gives them to chosen roles. Only ACCOUNTADMIN can manage the USE AI FUNCTIONS privilege. Neither database role can be granted directly to a user. You grant it to an account role, and then grant that account role to users.

USE ROLE ACCOUNTADMIN;

-- Remove blanket access from PUBLIC
REVOKE USE AI FUNCTIONS ON ACCOUNT FROM ROLE PUBLIC;

-- Create a role with access to only AI_COMPLETE
CREATE ROLE ai_complete_user_role;
GRANT USE AI FUNCTION AI_COMPLETE ON ACCOUNT TO ROLE ai_complete_user_role;
GRANT DATABASE ROLE SNOWFLAKE.CORTEX_USER TO ROLE ai_complete_user_role;

GRANT ROLE ai_complete_user_role TO USER example_user;

The two database roles differ in scope, and the difference matters for chat. AI_FUNCTIONS_USER covers the scalar AI functions only. It does not include the aggregate functions AI_AGG and AI_SUMMARIZE_AGG, and it gives no access to Cortex services such as Cortex Agent, Cortex Analyst or Cortex Search. It is also not granted to PUBLIC by default. A chat app that only calls AI_COMPLETE can run under AI_FUNCTIONS_USER. An app that calls an agent cannot, because agents need a different role (see the Cortex Agents lesson). Per-function grants and the blanket privilege work as an OR: a role with USE AI FUNCTIONS can call everything, whatever per-function grants it has or has lost.

Sources1

2.Multi-turn architecture: the messages array

The second argument of COMPLETE is called prompt_or_history, and the name explains what it does. Without the options argument, it must be a single prompt string. With options, even an empty object {}, it must be an array of message objects listed in the order they happened. Each object has a role key and a content key. This array is the parameter you update on every turn: add the user's new message, call the function, then add the model's reply as an assistant message so it is there for the next call.

This design has a cost. The history grows every turn, so the number of tokens processed also grows each round, and cost rises with it. Passing options also changes what comes back. Without options you get a plain string. With options but no response_format, you get a JSON string with choices (the reply), created, model and usage (completion_tokens, prompt_tokens, total_tokens). You can use the usage field to watch a conversation grow. The options object also sets the generation parameters listed below. AI_COMPLETE is the updated version of COMPLETE and the one to use for new code. The legacy COMPLETE page says that function will be deprecated by the end of 2026.

Sources23

3.Calling Cortex from application code

A Streamlit app or a Python script can call Cortex functions without writing SQL. The Snowpark Python API includes snake_case versions of the newer functions, such as ai_complete, ai_classify and ai_filter. Snowflake ML (snowflake.cortex) includes the older ones, such as complete, summarize and translate. If a script runs outside Snowflake, it must first create a Snowpark session. With Snowflake ML, you pass hyperparameters through a CompleteOptions object.

from snowflake.cortex import complete, CompleteOptions

model_options1 = CompleteOptions(
    {' ? ':30}
)

print(complete("llama3.1-8b", "how do snowflakes get their unique patterns?", options=model_options1))

For a chat app, one limitation matters more than any other. The multi-message, chat-style form of COMPLETE is not supported in Snowflake ML Python or in the Snowflake CLI. Those surfaces take a single prompt only. To send a messages array, call the function through SQL, for example from a Streamlit app that runs a query. On the app side, the conversation lives in client state. Snowflake's Streamlit agent guide keeps chat history in Streamlit session state to support multi-turn conversations. That client-held history is what you turn into prompt_or_history on each call.

Sources45

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.Granting USE AI FUNCTIONS to a role is enough to let it call AI_COMPLETE.Why is that wrong?

   The account privilege must be paired with the CORTEX_USER or AI_FUNCTIONS_USER database role. Either one alone is not enough.

   Covered in Setting up access: one privilege plus one database role

2. 2.Snowflake remembers earlier turns of a COMPLETE conversation, so the app only needs to send the newest question.Why is that wrong?

   COMPLETE is stateless. The app must resend all earlier prompts and responses, and the token cost grows each round.

   Covered in Multi-turn architecture: the messages array

3. 3.The Snowflake CLI command snow cortex complete can run a multi-turn conversation.Why is that wrong?

   The chat-style multi-message form of COMPLETE is not supported in the Snowflake CLI.

   Covered in Calling Cortex from application code