Category: Managed AI Function (Preview)

Description

Classifies text or images into user-defined categories using Vertex AI Gemini models. BigQuery automatically structures your input and optimizes prompts to improve classification quality. Returns a STRING containing the best-matching category.

Use Cases

Retail: Classify product reviews by sentiment (positive/negative/neutral)

Support: Route tickets by topic (billing/shipping/technical)

Content: Categorize news articles by subject

Image Analysis: Classify images by style or content

E-commerce: Categorize products automatically

Syntax

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

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

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

Parameters

INPUT: Text data from columns OR ObjectRefRuntime values from OBJ.GET_ACCESS_URL() for images/multimodal

CATEGORIES:

• Simple: ARRAY - e.g., ['positive', 'negative', 'neutral']

• With descriptions: ARRAY>

CONNECTION (optional): Connection ID format: project.location.connection_id

ENDPOINT (optional): Gemini model endpoint (auto-selected if omitted)

Code Examples

Example 1: Classify Customer Reviews

SELECT 
  review_text,
  AI.CLASSIFY(
    review_text,
    ['positive', 'negative', 'neutral'],
    connection_id => 'us.my_vertex_connection'
  ) AS sentiment
FROM customer_reviews
LIMIT 10

SELECT 
  review_text,
  AI.CLASSIFY(
    review_text,
    ['positive', 'negative', 'neutral'],
    connection_id => 'us.my_vertex_connection'
  ) AS sentiment
FROM customer_reviews
LIMIT 10

SELECT 
  review_text,
  AI.CLASSIFY(
    review_text,
    ['positive', 'negative', 'neutral'],
    connection_id => 'us.my_vertex_connection'
  ) AS sentiment
FROM customer_reviews
LIMIT 10

Example 2: Classify Support Tickets with Descriptions

SELECT 
  ticket_id,
  subject,
  AI.CLASSIFY(
    CONCAT(subject, ' ', description),
    [
      STRUCT('billing' AS category, 'Issues related to invoices, payments, or pricing' AS description),
      STRUCT('technical' AS category, 'Product functionality or bug reports' AS description),
      STRUCT('shipping' AS category, 'Delivery, tracking, or logistics questions' AS description),
      STRUCT('other' AS category, 'General inquiries or feedback' AS description)
    ],
    connection_id => 'us.my_vertex_connection'
  ) AS category
FROM support_tickets
WHERE status = 'open'

SELECT 
  ticket_id,
  subject,
  AI.CLASSIFY(
    CONCAT(subject, ' ', description),
    [
      STRUCT('billing' AS category, 'Issues related to invoices, payments, or pricing' AS description),
      STRUCT('technical' AS category, 'Product functionality or bug reports' AS description),
      STRUCT('shipping' AS category, 'Delivery, tracking, or logistics questions' AS description),
      STRUCT('other' AS category, 'General inquiries or feedback' AS description)
    ],
    connection_id => 'us.my_vertex_connection'
  ) AS category
FROM support_tickets
WHERE status = 'open'

SELECT 
  ticket_id,
  subject,
  AI.CLASSIFY(
    CONCAT(subject, ' ', description),
    [
      STRUCT('billing' AS category, 'Issues related to invoices, payments, or pricing' AS description),
      STRUCT('technical' AS category, 'Product functionality or bug reports' AS description),
      STRUCT('shipping' AS category, 'Delivery, tracking, or logistics questions' AS description),
      STRUCT('other' AS category, 'General inquiries or feedback' AS description)
    ],
    connection_id => 'us.my_vertex_connection'
  ) AS category
FROM support_tickets
WHERE status = 'open'

Example 3: Classify Product Images

-- Create object table
CREATE OR REPLACE EXTERNAL TABLE product_catalog.images
WITH CONNECTION us.my_vertex_connection
OPTIONS (
  object_metadata = 'SIMPLE',
  uris = ['gs://my-bucket/products/*.png']
);

-- Classify images
SELECT 
  STRING(OBJ.GET_ACCESS_URL(ref,'r').access_urls.read_url) AS image_url,
  AI.CLASSIFY(
    OBJ.GET_ACCESS_URL(ref, 'r'),
    ['apparel', 'electronics', 'home-goods', 'toys', 'other'],
    connection_id => 'us.my_vertex_connection'
  ) AS product_category
FROM product_catalog.images
LIMIT 20

-- Create object table
CREATE OR REPLACE EXTERNAL TABLE product_catalog.images
WITH CONNECTION us.my_vertex_connection
OPTIONS (
  object_metadata = 'SIMPLE',
  uris = ['gs://my-bucket/products/*.png']
);

-- Classify images
SELECT 
  STRING(OBJ.GET_ACCESS_URL(ref,'r').access_urls.read_url) AS image_url,
  AI.CLASSIFY(
    OBJ.GET_ACCESS_URL(ref, 'r'),
    ['apparel', 'electronics', 'home-goods', 'toys', 'other'],
    connection_id => 'us.my_vertex_connection'
  ) AS product_category
FROM product_catalog.images
LIMIT 20

-- Create object table
CREATE OR REPLACE EXTERNAL TABLE product_catalog.images
WITH CONNECTION us.my_vertex_connection
OPTIONS (
  object_metadata = 'SIMPLE',
  uris = ['gs://my-bucket/products/*.png']
);

-- Classify images
SELECT 
  STRING(OBJ.GET_ACCESS_URL(ref,'r').access_urls.read_url) AS image_url,
  AI.CLASSIFY(
    OBJ.GET_ACCESS_URL(ref, 'r'),
    ['apparel', 'electronics', 'home-goods', 'toys', 'other'],
    connection_id => 'us.my_vertex_connection'
  ) AS product_category
FROM product_catalog.images
LIMIT 20

Example 4: Group and Count by Category

SELECT 
  AI.CLASSIFY(
    article_text,
    ['technology', 'politics', 'sports', 'entertainment', 'business'],
    connection_id => 'us.my_vertex_connection'
  ) AS topic,
  COUNT(*) AS article_count
FROM news_articles
WHERE published_date >= CURRENT_DATE() - 7
GROUP BY topic
ORDER BY article_count DESC

SELECT 
  AI.CLASSIFY(
    article_text,
    ['technology', 'politics', 'sports', 'entertainment', 'business'],
    connection_id => 'us.my_vertex_connection'
  ) AS topic,
  COUNT(*) AS article_count
FROM news_articles
WHERE published_date >= CURRENT_DATE() - 7
GROUP BY topic
ORDER BY article_count DESC

SELECT 
  AI.CLASSIFY(
    article_text,
    ['technology', 'politics', 'sports', 'entertainment', 'business'],
    connection_id => 'us.my_vertex_connection'
  ) AS topic,
  COUNT(*) AS article_count
FROM news_articles
WHERE published_date >= CURRENT_DATE() - 7
GROUP BY topic
ORDER BY article_count DESC

Data Output Examples

Customer Review Sentiment

Support Ticket Classification

Best Practices

Include an 'other' category: For inputs that don't match well with defined categories

Use descriptive names: Make category names self-explanatory

Add descriptions for ambiguous cases: Use STRUCT format with category descriptions

Combine columns for context: Use CONCAT to merge multiple fields for richer analysis

Test with samples first: Validate category definitions before full deployment

When to Use

✅ Use AI.CLASSIFY when you have predefined categories

✅ Use for GROUP BY operations to segment data

✅ Use when you need consistent, managed performance

Alternatives

AI.GENERATE: For custom prompts with full control over model and parameters

Traditional CASE WHEN: For simple rule-based classification

AI.SCORE: If you need ranking instead of classification

Platform Support

Regions: All Gemini-supported regions + US/EU multi-regions

Preview Status: Currently in Preview (Pre-GA)

Cost: Charged per Vertex AI API call

Returns

STRING value containing the category that best fits the input. Returns NULL if the Vertex AI call fails.