The AI.CLASSIFY function

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

This document describes theAI.CLASSIFY function, which uses aVertex AI Gemini model to classifyinputs into categories that you provide. BigQuery automaticallystructuresyour input to improve the quality of the classification.

The following are common use cases:

• Retail: Classify reviews by sentiment or classify products by categories.
• Text analysis: Classify support tickets or emails by topic.

Input

AI.CLASSIFY accepts the following types of input:

• Text data from standard tables.

This function passes your input to a Gemini model andincurs charges in Vertex AI each time it's called.For information about how to view these charges, seeTrack costs.

Syntax

AI.CLASSIFY([input=>]'INPUT',[categories=>]'CATEGORIES',connection_id=>'CONNECTION')

Arguments

AI.CLASSIFY takes the following arguments:

• INPUT: aSTRING orSTRUCT value that specifies theinput to classify. The input must be the first argument that you specify.You can provide the input value in the following ways:

  • Specify aSTRING value. For example,'apple'.

  • Specify aSTRUCT value that contains one or more fields. You can usethe following types of fields within theSTRUCT value:

    Field type	Description	Examples
    STRING	A string literal, or the name of aSTRING column.	String literal: 'apple' String column name: my_string_column
    ARRAY<STRING>	You can only use string literals in the array.	Array of string literals: ['red ', 'apples']

    The function combinesSTRUCT fields similarly to aCONCAToperation and concatenates the fields in their specified order. Thesame is true for the elements of any arrays used within the struct.The following table shows some examples ofSTRUCT prompt values and howthey are interpreted:

    Struct field types	Struct value	Semantic equivalent
    STRUCT<STRING>	('apples')	'apples'
    STRUCT<STRING, STRING>	('red', ' apples')	'red apples'
    STRUCT<STRING, ARRAY<STRING>>	('crisp ', ['red', ' apples'])	'crisp red apples'

• CATEGORIES: the categories by which to classifythe input. You can specify categories with or without descriptions:

  • With descriptions: Use anARRAY<STRUCT<STRING, STRING>> value where eachstruct contains the category name, followed by a description of thecategory. The array can only contain string literals. For example,you could use colors to classify sentiment:

    [('green', 'positive'), ('yellow', 'neutral'), ('red', 'negative')]

    You can optionally name the fields of the struct for your own readability,but the field names aren't used by the function:

      [STRUCT('green' AS label, 'positive' AS description),   STRUCT('yellow' AS label, 'neutral' AS description),   STRUCT('red' AS label, 'negative' AS description)]

  • Without descriptions: Use anARRAY<STRING> value. The array can onlycontain string literals. This works well when your categories areself-explanatory. For example, you could use the following categoriesto classify sentiment:

    ['positive', 'neutral', 'negative']

  To handle input that doesn't closely match acategory, consider including an'Other' category.

• CONNECTION: aSTRING value specifying theCloud resource connectionto use. The following forms are accepted:

  • Connection name:[PROJECT_ID].LOCATION.CONNECTION_ID

    For example,myproject.us.myconnection.

  • Fully qualified connection ID:projects/PROJECT_ID/locations/LOCATION/connections/CONNECTION_ID

    For example,projects/myproject/locations/us/connections/myconnection.

  Replace the following:

  • PROJECT_ID: the project ID of the project that contains the connection.
  • LOCATION: thelocation used by the connection.
  • CONNECTION_ID: the connection ID—for example,myconnection.

    You can get this value byviewing the connection details in the Google Cloud console and copying the value in the last section of the fully qualified connection ID that is shown inConnection ID. For example,projects/myproject/locations/connection_location/connections/myconnection.

  Important

  You need to grant theVertex AI User role to the connection's service account. For more information, seeGrant or revoke a single IAM role.

Output

AI.CLASSIFY returns aSTRING value containing the provided category thatbest fits the input.

If the call to Vertex AI is unsuccessful for any reason,such as exceeding quota or model unavailability, then the function returnsNULL.

Examples

The following examples show how to use theAI.CLASSIFY function to classifytext and images into predefined categories.

Classify text by topic

The following query categorizes BBC news articles into high-level categories:

SELECTtitle,body,AI.CLASSIFY(body,categories=>['tech','sport','business','politics','entertainment','other'],connection_id=>'us.example_connection')AScategoryFROM`bigquery-public-data.bbc_news.fulltext`LIMIT100;

Classify reviews by sentiment

The following query classifies movie reviews of The English Patientby sentiment according to a customcolor scheme. For example, a review that is very positive is classified as'green'.

SELECTAI.CLASSIFY(('Classify the review by sentiment: ',review),categories=>[('green','The review is positive.'),('yellow','The review is neutral.'),('red','The review is negative.')],connection_id=>'us.example_connection')ASai_review_rating,reviewer_ratingAShuman_provided_rating,review,FROM`bigquery-public-data.imdb.reviews`WHEREtitle='The English Patient'

Locations

You can runAI.CLASSIFY in all of theregionsthat support Gemini models, and also in theUS andEUmulti-regions.

Quotas

SeeGenerative AI functions quotas and limits.

What's next

• For more information about using Vertex AI models togenerate text and embeddings, seeGenerative AI overview.
• For more information about using Cloud AI APIs to perform AI tasks, seeAI application overview.
• For more information about supported SQL statements and functions forgenerative AI models, seeEnd-to-end user journeys for generative AI models.
• To use this function in a tutorial, seePerform semantic analysis with managed AI functions.