Snowflake Gen AI Functions · Topic 2 of 26
AI_COMPLETE - Text, Image and Prompt Object Completions
Use AI_COMPLETE for general LLM prompts in SQL. Know its three input forms, model parameters and defaults, Cortex Guard, show_details output and errors.
- 4 min
AI_COMPLETEis the general function; it replacesSNOWFLAKE.CORTEX.COMPLETE.- Defaults:
temperature0,top_p0,max_tokens4096,guardrailsFALSE,show_detailsFALSE. - Three input forms: single string, single file, prompt object.
What it is
AI_COMPLETE generates a response from a text prompt, or from text plus images or documents, using a supported large language model. It is the general purpose Cortex AI function and the one to pick when no task specific function fits. Snowflake calls it the updated version of the older SNOWFLAKE.CORTEX.COMPLETE and recommends it for new work.
It can run on Snowflake hosted models from providers such as Anthropic, OpenAI, Meta, Mistral AI, DeepSeek and xAI. In open preview it can also call a text generation or vision model that you deploy as a Snowpark Container Services model inference service, by passing the service name as the model argument.
How it works
Three input forms
| Form | Input | Typical use |
|---|---|---|
| Single string | Model name and a text prompt | Questions, rewrites, classification by prompt |
| Single image or file | A prompt plus one staged file | Describe or read one image |
| Prompt object | A PROMPT(...) object with text and several files | Compare images, mix columns and files |
Single string syntax
AI_COMPLETE(<model>, <prompt>
[, <model_parameters>, <response_format>, <show_details>])
Arguments can be positional or named. A typical call over a table:
SELECT AI_COMPLETE(
model => 'llama3.3-70b',
prompt => CONCAT('Summarize this ticket in one sentence: ', ticket_text),
model_parameters => {'temperature': 0, 'max_tokens': 200}
) AS summary
FROM tickets;
Model names change often. SHOW CORTEX BASE MODELS lists what your account can use, so a scenario that asks how to find usable models points there. Which models exist in a region is also limited by regional availability.
Model parameters and defaults
| Parameter | Range | Default | Effect |
|---|---|---|---|
temperature | 0 to 1 | 0 | Higher gives more varied output |
top_p | 0 to 1 | 0 | Limits the tokens the model may choose from |
max_tokens | no range stated | 4096 | Maximum output tokens; small values truncate the answer |
guardrails | TRUE or FALSE | FALSE | Turns on Cortex Guard filtering |
The defaults favor repeatable answers. Raise temperature only when you want creative variety.
Cortex Guard
Setting guardrails to TRUE filters responses that may involve violent crimes, hate, sexual content, self harm and similar categories. Cortex Guard is built on Meta's Llama Guard 3. It adds a charge based on the input tokens it processes, on top of the normal AI_COMPLETE charge.
Return type and show_details
By default the function returns a string. If you pass a response_format, it returns an object that follows that format (see the structured outputs page). Setting show_details to TRUE returns a JSON object with the response and metadata.
- Without
response_format, that object haschoices,created,modelandusage. - With
response_format, it hasstructured_output,created,modelandusage. usageholdsprompt_tokens,completion_tokensandtotal_tokens.
Images and the prompt object
For images and documents, build the prompt with PROMPT and TO_FILE. Numbered placeholders {0}, {1} map to the files that follow the template.
SELECT AI_COMPLETE(
'claude-sonnet-4-6',
PROMPT('Compare {0} with {1} and list the differences.',
TO_FILE('@img_stage', 'before.png'),
TO_FILE('@img_stage', 'after.png'))
);
Only vision capable models accept files. Image formats include .jpg, .jpeg, .png, .gif and .webp, the stage must use server side encryption, and video or audio are not supported. A JSON schema for structured output is not supported with the prompt object form, so use the single string form when you need response_format.
Prompt text that comes from table columns is built with CONCAT for a single string call, and with PROMPT when files are involved.
Error handling
All forms accept an optional last argument return_error_details. By default a row that cannot be processed returns NULL and the query continues. With TRUE the result is an object with value and error.
Access
The role needs the usual USE AI FUNCTIONS privilege and the SNOWFLAKE.CORTEX_USER or AI_FUNCTIONS_USER database role. Container hosted models have their own requirements.
Do not confuse AI_COMPLETE with COMPLETE. The legacy SNOWFLAKE.CORTEX.COMPLETE takes an options object and a messages array, and Snowflake says it will be deprecated by the end of 2026.
Common mistakes
Expecting creative output at the defaults. With temperature 0 the answer is stable; raise it deliberately.
Setting max_tokens too low. The answer is cut off, not shortened.
Forgetting that guardrails costs extra. It adds input token charges on top of the call.
Passing a JSON schema with a prompt object. Use the single string form for response_format.
Hard coding a model name from memory. Check SHOW CORTEX BASE MODELS and regional availability.
What to remember for the exam
AI_COMPLETEis the general function; it replacesSNOWFLAKE.CORTEX.COMPLETE.- Defaults:
temperature0,top_p0,max_tokens4096,guardrailsFALSE,show_detailsFALSE. - Three input forms: single string, single file, prompt object.
guardrails => TRUEuses Cortex Guard (Llama Guard 3) and adds a charge.show_details => TRUEreturns the usage block with prompt, completion and total tokens.- Failed rows return
NULL;return_error_detailsgivesvalueanderror.
Check yourself
Which
AI_COMPLETEparameter turns on Cortex Guard?guardrailsinsidemodel_parameters, set toTRUE; it is off by default.What is the default
max_tokens, and what happens if it is too small?4096; the response is truncated.
How do you pass two staged images to
AI_COMPLETE?Build a
PROMPTobject with{0}and{1}placeholders and twoTO_FILEvalues, using a vision capable model.
Topic 2 of 26 in Snowflake Gen AI Functions
Test yourself on Snowflake Gen AI Functions
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.