AI_CLASSIFY is a SQL function in MaxCompute that classifies unstructured text and returns the label that best matches the input. - MaxCompute

AI_CLASSIFY is an AI function in MaxCompute that calls a model to return the label from a given list of candidates that best matches the input.

Syntax

STRING AI_CLASSIFY(
  STRING <model_name>,
  STRING <version_name>,
  STRING <input>,
  ARRAY<STRING> <labels>
  [, STRING <model_parameters>]
);

Parameters

model_name: Required. A string specifying the name of the model to use. For more information, see SQL AI functions.
version_name: Required. A string specifying the model version to use. To use the default version, specify DEFAULT_VERSION.
input: Required. A string containing the text to classify.
labels: Required. An array of candidate string labels. This parameter can be a constant or a column name. If you use a constant, it must contain between 2 and 20 labels.
model_parameters: Optional. A string specifying model parameters in JSON format, such as max_tokens, temperature, and top_p. For example:

'{"max_tokens": 500, "temperature": 0.6, "top_p": 0.95}'.
- max_tokens: The maximum number of tokens to generate in a single model call. The default for MaxCompute public models is 4096.
- temperature: A value between 0 and 1 that controls the randomness of the model's output. A higher value results in more creative and diverse output, while a lower value makes the output more deterministic and conservative.
- top_p: A value between 0 and 1 that limits the range of candidate labels the model considers. A higher value results in a wider range and more diversity, while a lower value results in a narrower range and more focused output.

Return value

Returns a string representing the single label that best matches the input.

The function returns an error if input is not of type STRING or labels is not of type ARRAY<STRING>.
The function returns an error if labels is a constant that contains fewer than 2 or more than 20 labels.
The function returns NULL if input or labels is NULL or an empty string ("").

Prerequisites

Before calling AI_CLASSIFY, enable the required session settings based on your model's access mode.

For public models accessed via the model computing service, run:

SET odps.task.major.version=sql_modelstudio;
SET odps.namespace.schema=true;

For public models accessed as common models, run:

SET odps.sql.ai.treat.as.common.model=true;
SET odps.namespace.schema=true;

Check your model's access mode to determine which setting applies. The examples below use each mode in turn.

Usage notes

To get accurate classification results:

Use plain, descriptive text in both input and labels. Avoid abbreviations, special characters, and jargon.
Use mutually exclusive labels. Overlapping categories (for example, "Technology" and "Software") reduce classification confidence.
Keep labels specific. Vague names such as "Category 1" or "Other" make it harder for the model to distinguish between options.
Avoid classifying non-prose content such as code snippets, log lines, or numeric data. The function is designed for natural-language text.

Use between 2 and 20 constant labels. For larger label sets, store labels in a table column and pass the column reference instead.

Examples

Example 1: Classify constant text

This example calls the qwen3-max public model provided by MaxCompute to classify an input text and return the best-matching label.

-- Use the model computing service in SQL jobs
SET odps.task.major.version=sql_modelstudio;
SET odps.namespace.schema=true;

SELECT AI_CLASSIFY(
    bigdata_public_modelset.default.`qwen3-max`,
    DEFAULT_VERSION,
    'MaxCompute is a fully managed, high-performance big data computing platform that provides fast and scalable data warehousing and analytics capabilities.',
    ARRAY('Technology', 'Sports', 'Finance', 'Healthcare', 'Education')
) AS classified_label;

-- Result
+------------------+
| classified_label |
+------------------+
| Technology       |
+------------------+

Example 2: Classify data in a table

This example calls the Qwen3-4B-GGUF public model provided by MaxCompute to batch-classify multiple text entries in a table.

-- Sample data
CREATE TABLE news_articles (
    content STRING
);

INSERT INTO news_articles VALUES
    ('Artificial intelligence is transforming the healthcare industry with new diagnostic tools.'),
    ('The stock market hit a new all-time high today, driven by a rally in the tech sector.'),
    ('The team won the championship after a thrilling overtime game.'),
    ('Cloud computing allows businesses to scale their infrastructure on demand.');

-- Call the model to classify the text in the table
SET odps.sql.ai.treat.as.common.model=true;
SET odps.namespace.schema=true;

SELECT
    content,
    AI_CLASSIFY(
        bigdata_public_modelset.default.`Qwen3-4B-GGUF`,
        DEFAULT_VERSION,
        content,
        ARRAY('Technology', 'Sports', 'Finance', 'Healthcare')
    ) AS category
FROM news_articles;

-- Result
+------------------------------------------------------------------------------------------+------------+
| content                                                                                  | category   |
+------------------------------------------------------------------------------------------+------------+
| Artificial intelligence is transforming the healthcare industry with new diagnostic tools. | Healthcare |
| The stock market hit a new all-time high today, driven by a rally in the tech sector.    | Finance    |
| The team won the championship after a thrilling overtime game.                            | Sports     |
| Cloud computing allows businesses to scale their infrastructure on demand.               | Technology |
+------------------------------------------------------------------------------------------+------------+