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
AI_COUNT_TOKENSestimates input tokens and returns anINTEGER; it costs compute only.- It needs lowercase names and a model for
ai_completeandai_embed. - It does not support images, legacy
SNOWFLAKE.CORTEXfunctions 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_TOKENSestimates how many input tokens a call would use, before you run it.TRY_COMPLETEbehaves likeCOMPLETEbut returnsNULLinstead of raising an error.
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
INTEGERestimate 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.CORTEXlegacy 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 withreturn_error_detailsset toTRUEan object withvalueanderror. - 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.
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 withroleandcontentkeys, in chronological order. optionscan holdtemperature(default 0),top_p(default 0),max_tokens(default 4096, maximum 8192),guardrails(defaultFALSE) andresponse_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.
| Need | Current approach |
|---|---|
| Keep a batch running when a row fails | AI_COMPLETE (default NULL) |
| See why a row failed | AI_COMPLETE with return_error_details set to TRUE |
Existing code that uses COMPLETE and must not fail | TRY_COMPLETE |
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_TOKENSestimates input tokens and returns anINTEGER; it costs compute only.- It needs lowercase names and a model for
ai_completeandai_embed. - It does not support images, legacy
SNOWFLAKE.CORTEXfunctions or fine tuned models. TRY_COMPLETEreturnsNULLwhereCOMPLETEwould raise an error.COMPLETEandTRY_COMPLETEare legacy and slated for deprecation by the end of 2026.- Real billed usage is in
CORTEX_AISQL_USAGE_HISTORYandCORTEX_AI_FUNCTIONS_USAGE_HISTORY, not the olderCORTEX_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_COMPLETEdiffer fromCOMPLETE?It returns
NULLinstead of raising an error when the operation cannot be performed.Why can the billed tokens exceed the
AI_COUNT_TOKENSresult?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.