Snowflake Gen AI Functions · Topic 11 of 26

Helper Functions - AI_COUNT_TOKENS and TRY_COMPLETE

Estimate token use before a large run with AI_COUNT_TOKENS and handle model errors with TRY_COMPLETE. Know syntax, limits, billing and AI_COMPLETE links.

  • 4 min
In a nutshell
  • AI_COUNT_TOKENS estimates input tokens and returns an INTEGER; it costs compute only.
  • It needs lowercase names and a model for ai_complete and ai_embed.
  • It does not support images, legacy SNOWFLAKE.CORTEX functions or fine tuned models.

What it is

Helper functions do not call a model to produce an answer. They prepare inputs, estimate cost or make a call safer. The documented Cortex helper functions are TO_FILE, PROMPT and AI_COUNT_TOKENS, and the text splitters do similar preparation work. TRY_COMPLETE is a related legacy helper for error handling.

  • AI_COUNT_TOKENS estimates how many input tokens a call would use, before you run it.
  • TRY_COMPLETE behaves like COMPLETE but returns NULL instead of raising an error.
Large tableof promptsestimateAI_COUNT_TOKENSinput tokensbudget checkAI_COMPLETEproduction runerrorsNULL or error object

How it works

AI_COUNT_TOKENS

AI_COUNT_TOKENS(<function_name>, [<model_name>,] <input_text> [, <options>] [, <return_error_details>])

The first argument names the function you plan to run, in lowercase and starting with ai_. The model name is required for functions where you choose a model, such as ai_complete and ai_embed.

SELECT AI_COUNT_TOKENS('ai_complete', 'llama3.3-70b', prompt_text) AS tokens
FROM prompts;

SELECT AI_COUNT_TOKENS('ai_translate', text, 'fr', 'en') FROM docs;

Some functions have their own shape. ai_similarity takes two input texts plus options, ai_classify takes the input text and the categories (categories count toward the total), and ai_translate takes the text, a source language and a target language.

Supported functions: AI_COMPLETE, AI_EMBED, AI_SIMILARITY with a chosen model, and AI_CLASSIFY, AI_SENTIMENT, AI_SUMMARIZE, AI_REDACT and AI_TRANSLATE with their default model.

Key facts:

  • It returns an INTEGER estimate of input tokens only. Output tokens are not included, but they are billed.
  • It accepts text only, not images, audio or video.
  • It does not work with the SNOWFLAKE.CORTEX legacy functions or with fine tuned models.
  • It is available in all regions, even where a supported model is not.
  • On error it returns NULL, or with return_error_details set to TRUE an object with value and error.
  • It costs compute only. It is not billed by token count.
  • It is the updated version of COUNT_TOKENS.

Billed totals can be higher than the estimate. AI_COMPLETE with response_format on Anthropic Claude models adds structured output content, and AI_TRANSLATE, AI_SUMMARIZE and AI_REDACT generate output text that is billed too. Accuracy varies by model, with exact matches for many and small percentage errors for some.

To see what was really billed, use the CORTEX_AISQL_USAGE_HISTORY and CORTEX_AI_FUNCTIONS_USAGE_HISTORY views in ACCOUNT_USAGE; the older CORTEX_FUNCTIONS_QUERY_USAGE_HISTORY view is no longer updated.

Exam tip

A question about "estimate the cost before running over millions of rows" has the answer AI_COUNT_TOKENS, often followed by a trial on a small sample.

TRY_COMPLETE

SNOWFLAKE.CORTEX.TRY_COMPLETE(<model>, <prompt_or_history> [, <options>])

It "performs the same operation as the COMPLETE function" but returns NULL instead of raising an error when the call cannot be completed. The syntax matches SNOWFLAKE.CORTEX.COMPLETE.

  • Without options, the second argument is a string and the result is a string.
  • With options, the second argument is an array of objects with role and content keys, in chronological order.
  • options can hold temperature (default 0), top_p (default 0), max_tokens (default 4096, maximum 8192), guardrails (default FALSE) and response_format.
SELECT id, SNOWFLAKE.CORTEX.TRY_COMPLETE('llama3.3-70b', prompt_text) AS answer
FROM prompts
WHERE answer IS NOT NULL;

The role needs USE AI FUNCTIONS and SNOWFLAKE.CORTEX_USER.

How TRY_COMPLETE relates to AI_COMPLETE

TRY_COMPLETE is kept for backward compatibility, and Snowflake says it will be deprecated by the end of 2026. AI_COMPLETE already returns NULL for a failed row by default, and gives an error message when return_error_details is TRUE.

NeedCurrent approach
Keep a batch running when a row failsAI_COMPLETE (default NULL)
See why a row failedAI_COMPLETE with return_error_details set to TRUE
Existing code that uses COMPLETE and must not failTRY_COMPLETE
Watch out

A NULL from TRY_COMPLETE hides the reason for the failure. Add a check for NULL results, and move to AI_COMPLETE with return_error_details when you need the message.

Common mistakes

Calling AI_COUNT_TOKENS with uppercase names. Function and model names must be lowercase.

Treating the count as the full bill. It covers input only, and output tokens are billed too.

Counting tokens for an image. Only text is supported.

Using AI_COUNT_TOKENS on SNOWFLAKE.CORTEX.COMPLETE calls. Legacy functions are not supported.

Using TRY_COMPLETE in new designs. AI_COMPLETE is the recommended function.

What to remember for the exam

  • AI_COUNT_TOKENS estimates input tokens and returns an INTEGER; it costs compute only.
  • It needs lowercase names and a model for ai_complete and ai_embed.
  • It does not support images, legacy SNOWFLAKE.CORTEX functions or fine tuned models.
  • TRY_COMPLETE returns NULL where COMPLETE would raise an error.
  • COMPLETE and TRY_COMPLETE are legacy and slated for deprecation by the end of 2026.
  • Real billed usage is in CORTEX_AISQL_USAGE_HISTORY and CORTEX_AI_FUNCTIONS_USAGE_HISTORY, not the older CORTEX_FUNCTIONS_* views.

Check yourself

  • Which function estimates the tokens of a prompt before a large run?

    AI_COUNT_TOKENS, which returns an integer estimate of input tokens.

  • How does TRY_COMPLETE differ from COMPLETE?

    It returns NULL instead of raising an error when the operation cannot be performed.

  • Why can the billed tokens exceed the AI_COUNT_TOKENS result?

    Output tokens are billed but not counted, and some functions add extra content.

Topic 11 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.