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
In a nutshell
  • AI_COMPLETE is the general function; it replaces SNOWFLAKE.CORTEX.COMPLETE.
  • Defaults: temperature 0, top_p 0, max_tokens 4096, guardrails FALSE, show_details FALSE.
  • 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

FormInputTypical use
Single stringModel name and a text promptQuestions, rewrites, classification by prompt
Single image or fileA prompt plus one staged fileDescribe or read one image
Prompt objectA PROMPT(...) object with text and several filesCompare images, mix columns and files
Text columnor PROMPT objectpromptAI_COMPLETEmodel + promptruns onSnowflake hosted LLMinside the perimeterreturnsStringor object

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

ParameterRangeDefaultEffect
temperature0 to 10Higher gives more varied output
top_p0 to 10Limits the tokens the model may choose from
max_tokensno range stated4096Maximum output tokens; small values truncate the answer
guardrailsTRUE or FALSEFALSETurns 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 has choices, created, model and usage.
  • With response_format, it has structured_output, created, model and usage.
  • usage holds prompt_tokens, completion_tokens and total_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.

Exam tip

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.

Watch out

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_COMPLETE is the general function; it replaces SNOWFLAKE.CORTEX.COMPLETE.
  • Defaults: temperature 0, top_p 0, max_tokens 4096, guardrails FALSE, show_details FALSE.
  • Three input forms: single string, single file, prompt object.
  • guardrails => TRUE uses Cortex Guard (Llama Guard 3) and adds a charge.
  • show_details => TRUE returns the usage block with prompt, completion and total tokens.
  • Failed rows return NULL; return_error_details gives value and error.

Check yourself

  • Which AI_COMPLETE parameter turns on Cortex Guard?

    guardrails inside model_parameters, set to TRUE; 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 PROMPT object with {0} and {1} placeholders and two TO_FILE values, 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.