Snowflake Gen AI Functions · Topic 4 of 26

Task-Specific Functions - AI_CLASSIFY, AI_SENTIMENT and AI_FILTER

Choose the right task-specific Cortex function for labels, sentiment and yes/no filtering. Know categories, output modes, limits and return formats.

  • 4 min
In a nutshell
  • Task specific functions have a built in prompt and need no model argument.
  • AI_CLASSIFY takes at least two categories, optional task_description, output_mode (single default, or multi) and examples.
  • AI_SENTIMENT accepts up to ten categories of 30 characters or less and returns unknown, positive, negative, neutral or mixed, always with an overall entry.

What it is

Task-specific functions are Cortex AI functions that do one job with a built in prompt. You do not pick a model or write instructions, which makes them simpler and more predictable than AI_COMPLETE. Three of them decide or label a value for each row.

FunctionQuestion it answersReturns
AI_CLASSIFYWhich category does this input belong to?Object with a labels array
AI_SENTIMENTHow does the writer feel, overall or about aspects?Object with a categories array
AI_FILTERIs this statement true for this row?BOOLEAN

All three need USE AI FUNCTIONS plus the SNOWFLAKE.CORTEX_USER database role (or AI_FUNCTIONS_USER).

How it works

Column of textor imagesrow by rowTask specific functionbuilt in promptreturnsLabel, sentimentor TRUE and FALSEused inSELECT, WHERE, JOINand GROUP BY

AI_CLASSIFY

AI_CLASSIFY(<input>, <list_of_categories> [, <config_object>] [, <return_error_details>])

The input can be a string, an image, a document or a prompt object. The category list needs at least two unique values, each either a string or an object with a required label and an optional description of up to 25 words. Categories are case sensitive.

SELECT ticket_text,
       AI_CLASSIFY(ticket_text,
         ['billing', 'technical', 'account'],
         {'task_description': 'Support ticket routing',
          'output_mode': 'single'}):labels[0]::STRING AS category
FROM tickets;

The config object accepts three keys.

  • task_description explains the job, up to 50 words.
  • output_mode is 'single' (default, one label) or 'multi' (several labels allowed).
  • examples gives few shot examples, each with input, labels and explanation.

Accuracy can fall beyond about 20 categories, and documents are limited to 100 categories per call. For document input output_mode must be 'single' and examples is not supported. Document input is a preview feature.

Cost note: category labels, descriptions and examples are counted as input tokens for every row, so keep them short.

Exam tip

"Tickets can belong to several topics" in a scenario points to output_mode of 'multi'. "Exactly one department" points to the default.

AI_SENTIMENT

AI_SENTIMENT(<text> [, <categories>] [, <return_error_details>])

Without categories it returns only an overall result. With up to ten categories (each 30 characters or less), it returns a result for each aspect plus overall. Each entry has a name and a sentiment of unknown, positive, negative, neutral or mixed. unknown means the aspect is not mentioned.

SELECT AI_SENTIMENT(review, ['cost', 'quality', 'delivery']) FROM reviews;

The result is a label, not a numeric score. Its context window is 2,048 tokens (about 1,600 words), and longer input returns an error. It supports English, French, German, Hindi, Italian, Spanish and Portuguese. Snowflake describes AI_SENTIMENT as the updated version of ENTITY_SENTIMENT.

AI_FILTER

AI_FILTER(<input>)                           -- text predicate
AI_FILTER(<predicate>, <image_file>)         -- image
AI_FILTER(PROMPT('<template>', <col1>, ...)) -- several columns or files

AI_FILTER turns a natural language statement into TRUE or FALSE, so it can sit in a WHERE clause or in a JOIN ... ON condition.

SELECT * FROM reviews
WHERE AI_FILTER(PROMPT('The reviewer praises the food: {0}', review_text));

The documentation advises plain English, specific context, and phrasing the input as a question. Avoid NULL values in the input columns. A built in optimization can make qualifying queries 2 to 10 times faster and use up to 60 percent fewer tokens, but Snowflake does not guarantee it for every query.

Image input and regions

Text input works in all listed regions. Image input for AI_CLASSIFY and AI_FILTER is limited to a few regions, and AI_CLASSIFY accepts images up to 2000 by 2000 pixels. Neither function can read files from user stages, table stages, stages with double quoted names or the client side encrypted stage types.

Choosing between them

NeedUse
Put each row in one of your own categoriesAI_CLASSIFY
Tag a row with several topicsAI_CLASSIFY with 'multi'
Opinion per aspect such as price or serviceAI_SENTIMENT with categories
Keep only rows that satisfy a plain English ruleAI_FILTER in WHERE
Match two tables on meaning, such as resumes to jobsAI_FILTER in JOIN ON
Watch out

A classification returns an object, not a bare string. Read the label with :labels[0], or the next step receives JSON.

Common mistakes

Passing one category. At least two unique categories are required.

Expecting a number from AI_SENTIMENT. It returns labels such as positive or mixed.

Using more than ten sentiment categories or labels longer than 30 characters. Both exceed the limits.

Using AI_COMPLETE with a long prompt when AI_FILTER or AI_CLASSIFY is enough. The task specific function is simpler and cheaper to maintain.

Forgetting that labels are case sensitive. Billing and billing are different categories.

What to remember for the exam

  • Task specific functions have a built in prompt and need no model argument.
  • AI_CLASSIFY takes at least two categories, optional task_description, output_mode (single default, or multi) and examples.
  • AI_SENTIMENT accepts up to ten categories of 30 characters or less and returns unknown, positive, negative, neutral or mixed, always with an overall entry.
  • AI_FILTER returns a BOOLEAN and works in WHERE and JOIN ON.
  • All three return NULL for a failed row unless return_error_details is TRUE.

Check yourself

  • Which AI_CLASSIFY option allows more than one label per row?

    output_mode set to 'multi' in the config object.

  • What does unknown mean in an AI_SENTIMENT result?

    The aspect category is not mentioned in the text.

  • How do you join two tables on meaning with Cortex?

    Use AI_FILTER, usually with PROMPT, in the JOIN ... ON condition.

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