This page lists functions and their parameters, which are provided by the
`google_ml_integration` extension to register and manage model endpoints, and to use AI functions (such as `ai.if`, `ai.rank`, and `ai.generate`) with
model endpoint management.

## Before you begin

Before you register and manage model endpoints, verify the following:

- The [`google_ml_integration` extension is installed](https://docs.cloud.google.com/alloydb/docs/ai/configure-vertex-ai.md.txt#verify-installed-extension), and the `google_ml_integration` extension is updated to version 1.6.3 or later.
- The [`google_ml_integration.enable_model_support` flag is set to `on`](https://docs.cloud.google.com/alloydb/docs/instance-configure-database-flags.md.txt).
- The `google_ml_integration.enable_cost_optimized_ai_functions` database flag is set to `on`. For more information, see [Accelerate queries using optimized functions](https://docs.cloud.google.com/alloydb/docs/ai/accelerate-queries-optimized-functions.md.txt).

For more information, see [Register and call remote AI models in AlloyDB overview](https://docs.cloud.google.com/alloydb/docs/ai/model-endpoint-overview.md.txt).

## Schemas

The following lists the schemas and functions available in a schema.

`public` schema
:   The `embedding()` function in the `public` schema can be used with any Gemini Enterprise Agent Platform embedding model without registering the endpoint. For more information, see [Run similarity search](https://docs.cloud.google.com/alloydb/docs/ai/run-vector-similarity-search.md.txt).

`google_ml` schema
:   The `google_ml` schema provides the following functions:  

    - The [`google_ml.create_model()`](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#create-model) SQL function, which is used to register the model endpoint that is used in the prediction or embedding function.
    - The [`google_ml.create_sm_secret()`](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#create-secret) SQL function, which uses secrets in the Secret Manager, where the API keys are stored.
    - The [`google_ml.embedding()`](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#embedding) SQL function, which is a prediction function that generates text embeddings. The return type of the embedding function is REAL\[\].
    - The [`google_ml.text_embedding`](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#ai-text-embedding) SQL function in the AI functions, which generates single text embedding for a given query when using the multimodal endpoint.
    - The [`google_ml.image_embedding`](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#ai-image-embedding) SQL function in the AI functions, which generates a single embedding for the input image using a multimodal embedding model. The return type of the embedding function is REAL\[\].
    - The [`google_ml.rank()`](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#ranking-vertexai) SQL function in the AI functions, which improves the order of search results by ranking or ordering a collection of records in relation to a given query (a search string).
    - The [`google_ml.predict_row()`](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#predict-row) SQL function that generates predictions when you call generic models that support JSON input and output format.
    - Other helper functions that handle [generating custom URL](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#request-gen-Function), [generating HTTP headers](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#header-gen-function), or [passing transform functions](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#transform-function).
    - Functions to manage the [registered model endpoints](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#models) and [secrets](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#secrets).
    - The [`google_ml.if`](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#ai-if) SQL function in the AI functions filters and joins data. It evaluates conditions that you specify using natural language, with optional query acceleration using [local proxy models and vector embeddings](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#ai-if-optimized).
    - The [`google_ml.rank`](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#ai-score) SQL function in the AI functions, to order a list of items in a query based on a criteria stated using natural language.
    - The [`google_ml.generate`](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#ai-generate-Text) SQL function in the AI functions, to generate text based on prompts specified in natural language.
    - The [`google_ml.summarize`](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#ai-summarize) ([Preview](https://cloud.google.com/products#product-launch-stages)) SQL function in the AI functions, to summarize text content individually, in batches, or using cursors.
    - The [`google_ml.analyze_sentiment`](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#ai-analyze-sentiment) ([Preview](https://cloud.google.com/products#product-launch-stages)) SQL function in the AI functions, to perform sentiment analysis on text data individually, in batches, or using cursors.
    - The [`google_ml.agg_summarize`](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#ai-agg-summarize) ([Preview](https://cloud.google.com/products#product-launch-stages)) SQL function in the AI functions, which combines text across multiple rows and generates a single summary.
    - Functions and procedures to manage and retrain proxy models for optimized AI functions:
      - [`google_ml.retrain_optimized_model()`](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#retrain-optimized-model)
      - [`google_ml.retrain_optimized_models()`](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#retrain-optimized-models)
      - [`google_ml.delete_optimized_model()`](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#delete-optimized-model)
      - [`google_ml.delete_all_optimized_models()`](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#delete-all-optimized-models)
    - Views to monitor proxy models for optimized AI functions: [`google_ml.optimized_functions_view`](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#optimized-functions-view) and [`google_ml.proxy_training_jobs`](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#proxy-training-jobs).

`ai` schema
:   AlloyDB reserves, and creates, the `ai` schema.   

    The `ai` schema provides the following functions:   

    - The [`ai.text_embedding`](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#ai-text-embedding) SQL function in the AI functions, which generates single text embedding for a given query when using multimodal endpoint.
    - The [`ai.image_embedding`](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#ai-image-embedding) SQL function, which generates a single embedding for the input image. The return type of the embedding function is REAL\[\].
    - The [`ai.video_embedding`](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#ai-video-embedding) SQL function in the AI functions, which generates an array with one entry for each `interval_seconds` segment of the video defined when creating the multimodal endpoint.
    - The [`ai.if`](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#ai-if) SQL function in the AI functions filters and joins data. It evaluates conditions that you specify using natural language, with optional query acceleration using [local proxy models and vector embeddings](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#ai-if-optimized).
    - The [`ai.rank`](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#ai-score) SQL function in the AI functions, to order a list of items in a query based on a criteria stated using natural language.
    - The [`ai.generate`](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#ai-generate-Text) SQL function in the AI functions, to generate text based on prompts specified in natural language.
    - The [`ai.summarize`](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#ai-summarize) ([Preview](https://cloud.google.com/products#product-launch-stages)) SQL function in the AI functions, to summarize text content individually, in batches, or using cursors.
    - The [`ai.analyze_sentiment`](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#ai-analyze-sentiment) ([Preview](https://cloud.google.com/products#product-launch-stages)) SQL function in the AI functions, to perform sentiment analysis on text data individually, in batches, or using cursors.
    - The [`ai.agg_summarize`](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#ai-agg-summarize) ([Preview](https://cloud.google.com/products#product-launch-stages)) SQL function in the AI functions, which combines text across multiple rows and generates a single summary.
    - Functions and procedures to manage and retrain proxy models for optimized AI functions:
      - [`ai.retrain_optimized_model()`](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#retrain-optimized-model)
      - [`ai.retrain_optimized_models()`](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#retrain-optimized-models)
      - [`ai.delete_optimized_model()`](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#delete-optimized-model)
      - [`ai.delete_all_optimized_models()`](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#delete-all-optimized-models)
    - The [`ai.optimized_functions_view`](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#optimized-functions-view) view to monitor existing proxy models and their training status.

## Model provider

The following table shows
the model provider value that you can set based on the model provider that you use:

| Model provider | Set in function as... |
|---|---|
| Agent Platform | `google` |
| Hugging Face models | `hugging_face` |
| Anthropic models | `anthropic` |
| OpenAI | `open_ai` |
| Other models | `custom` |

The default model provider is `custom`.

Based on the provider type, the supported authentication method differs. The Agent Platform models use the AlloyDB service account to authenticate, while other providers can use the Secret Manager or pass authentication details through headers. For more information, see [Set up authentication](https://docs.cloud.google.com/alloydb/docs/ai/register-model-endpoint.md.txt#set_up_auth).

## Model type

The following sections describe the model type values that you can set.

> [!NOTE]
> **Note:** Setting model type is optional when registering generic model endpoints as `generic` is the default model type.

Pre-registered Agent Platform models
:   Within model endpoint management, a variety of Agent Platform models are supported as pre-registered model IDs. You can use these IDs directly in prediction or embedding functions without manual registration. To view the full list of supported models in your environment, run the following query:  

            SELECT * FROM google_ml.model_info_view;


    <br />

    For more information about supported pre-registered models, see [Pre-registered Agent Platform models](https://docs.cloud.google.com/alloydb/docs/reference/supported-ai-models.md.txt#pre-registered-models).  
    For example, to call the pre-registered `gemini-embedding-001` model directly:  

    ```
    SELECT
          google_ml.embedding(
            model_id => 'gemini-embedding-001',
            content => 'AlloyDB is a managed, cloud-hosted SQL database service');
    ```

Models with built-in support
:
    Model endpoints with built-in support benefit from automated integration. For Agent Platform, many of these models are pre-registered and can be used without manual setup. For other providers, such as OpenAI and Anthropic, you must register the model endpoint using its qualified name to enable the automated features.
:
    Built-in support simplifies registration and usage by automatically configuring default transform functions and inferring correct request URLs.
:   Model endpoint management provides built-in support for some models by Agent Platform, Anthropic, and OpenAI. For text embedding models with built-in support, AlloyDB
    automatically sets up default transform functions.
:   To enable automated integration for providers other than Agent Platform, you must register the model endpoint using its qualified name. For more information about models with built-in support, see [Models with built-in support](https://docs.cloud.google.com/alloydb/docs/reference/supported-ai-models.md.txt#models-built-in-support).

Other text embedding models
:   To register a text embedding model endpoint without built-in support, we recommend that you
    create transform functions to handle the input and output formats that
    the model supports. Optionally, depending on the model requirements, you might
    also need to create custom header function to specify the header.
:   The model type for these models is `text-embedding`.

Generic models
:   The model endpoint management also supports
    registering of all other model types apart from text embedding models. To
    invoke predictions for generic models, use the
    `google_ml.predict_row()` function. You can set model endpoint metadata,
    such as a request endpoint and HTTP headers that are specific to your model.
:   You cannot
    pass transform functions when you are registering a generic model endpoint. Ensure that
    when you invoke predictions the input to the function is in the JSON format, and
    that you parse the JSON output to derive the final output.
:   The model type for these models is `generic`.

Multimodal embedding models
:   Multimodal embeddings allow using vector representation for images, text and videos interchangeably. Multimodal embedding models generate the embeddings for different modalities in the same semantic space. This means semantically similar information, regardless of its original form, is located close together in the vector space.
:   You don't need to register the Agent Platform multimodal model because you can use the qualified name of the Agent Platform multimodal model as the model ID in your queries.
:   The model type for these models is `multimodal_embedding`.

Ranking models
:   Ranking models take a list of documents and rank those documents based on how relevant the documents are to a given query (a search string). The `ai.rank()` function can be used to return scores for how well a document answers a given query or to identify ranking of the items in a query based on a criteria specified in natural language.
:   The model type for these models is `reranking`.

## Authentication

For Vertex AI models, the AlloyDB service account is used for authentication. For other models,
API key or bearer token that is stored as a secret in the
Secret Manager can be used with the `google_ml.create_sm_secret()` SQL
function. If you are passing authentication through headers, then you can skip setting the authentication method.

The following table shows the auth types that you can set:

| Authentication method | Set in function as... | Model provider |
|---|---|---|
| AlloyDB service agent | `alloydb_service_agent_iam` | Agent Platform provider |
| Secret Manager | `secret_manager` | third-party providers, such as Anthropic, Hugging Face, or OpenAI |

## Models

Use this reference to understand parameters for functions that let you manage
model endpoints.

### `google_ml.create_model()` function

The following shows how to call the `google_ml.create_model()` SQL function used
to [register model endpoint](https://docs.cloud.google.com/alloydb/docs/ai/register-model-endpoint.md.txt) metadata:

```sql
  CALL
    google_ml.create_model(
      model_id => 'MODEL_ID',
      model_request_url => 'REQUEST_URL',
      model_provider => 'PROVIDER_ID',
      model_type => 'MODEL_TYPE',
      model_qualified_name => 'MODEL_QUALIFIED_NAME',
      model_auth_type => 'AUTH_TYPE',
      model_auth_id => 'AUTH_ID',
      generate_headers_fn => 'GENERATE_HEADER_FUNCTION',
      model_in_transform_fn => 'INPUT_TRANSFORM_FUNCTION',
      model_out_transform_fn => 'OUTPUT_TRANSFORM_FUNCTION');
```

| Parameter | Required | Description |
|---|---|---|
| `MODEL_ID` | required for all model endpoints | A unique ID for the model endpoint that you define. |
| `REQUEST_URL` | optional for other text embedding model endpoints with built-in support | The model-specific endpoint when adding other text embedding and generic model endpoints. For AlloyDB, provide an `https` URL. The request URL that the function generates for built-in model endpoints refers to your cluster's project and region or location. If you want to refer to another project, then ensure that you specify the `model_request_url` explicitly. For information about inferring request URLs for built-in model endpoints, see [Request URL generation](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#request-gen-Function). For custom hosted model endpoints, ensure that the model endpoint is accessible from the network where AlloyDB is located. |
| `PROVIDER_ID` | required for text embedding model endpoints with built-in support | The provider of the model endpoint. The default value is `custom`. Set to one of the following: - `google` for Agent Platform model endpoints - `open_ai` for OpenAI model endpoints - `hugging_face` for Hugging Face model endpoints - `anthropic` for Anthropic model endpoints - `custom` for other providers |
| `MODEL_TYPE` | optional for generic model endpoints | The model type. Set to one of the following: - `text_embedding` for text embedding model endpoints - `multimodal_embedding` for multimodal embedding model endpoints - `reranking` for ranking model endpoints - `generic` for all other model endpoints |
| `MODEL_QUALIFIED_NAME` | required for text embedding models with built-in support; optional for other model endpoints | The fully qualified name for text embedding models with built-in support. For Agent Platform qualified names that you must use for pre-registered models, see [Pre-registered Agent Platform models](https://docs.cloud.google.com/alloydb/docs/reference/supported-ai-models.md.txt#pre-registered-models). For qualified names that you must use for OpenAI models with built-in support, see [Models with built-in support](https://docs.cloud.google.com/alloydb/docs/reference/supported-ai-models.md.txt#models-built-in-support). |
| `AUTH_TYPE` | optional unless the model endpoint has specific authentication requirement | The authentication type used by the model endpoint. You can set it to either `alloydb_service_agent_iam` for Agent Platform models or `secret_manager` for other providers, if they use Secret Manager for authentication. You don't need to set this value if you are using authentication headers. |
| `AUTH_ID` | don't set for Agent Platform model endpoints; required for all other model endpoints that store secrets in Secret Manager | The secret ID that you set and is subsequently used when registering a model endpoint. |
| `GENERATE_HEADER_FUNCTION` | optional | The name of the function that generates custom headers. For Anthropic models, model endpoint management provides a `google_ml.anthropic_claude_header_gen_fn` function that you can use for default versions. The signature of this function depends on the prediction function that you use. See [Header generation function](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#header-gen-function). |
| `INPUT_TRANSFORM_FUNCTION` | optional for text embedding model endpoints with built-in support; don't set for generic model endpoints | The function to transform input of the corresponding prediction function to the model-specific input. See [Transform functions](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#transform-function). |
| `OUTPUT_TRANSFORM_FUNCTION` | optional for text embedding model endpoints with built-in support; don't set for generic model endpoints | The function to transform model specific output to the prediction function output. See [Transform functions](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#transform-function). |

### `google_ml.alter_model()`

The following shows how to call the `google_ml.alter_model()` SQL function used
to update model endpoint metadata:

```sql
    CALL
    google_ml.alter_model(
      model_id => 'MODEL_ID',
      model_request_url => 'REQUEST_URL',
      model_provider => 'PROVIDER_ID',
      model_type => 'MODEL_TYPE',
      model_qualified_name => 'MODEL_QUALIFIED_NAME',
      model_auth_type => 'AUTH_TYPE',
      model_auth_id => 'AUTH_ID',
      generate_headers_fn => 'GENERATE_HEADER_FUNCTION',
      model_in_transform_fn => 'INPUT_TRANSFORM_FUNCTION',
      model_out_transform_fn => 'OUTPUT_TRANSFORM_FUNCTION');
```

For information about the values that you must set for each parameter, see [Create a model](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#create-model).

### `google_ml.drop_model()` function

The following shows how to call the `google_ml.drop_model()` SQL function used
to drop a model endpoint:

```sql
  CALL google_ml.drop_model('MODEL_ID');
```

| Parameter | Description |
|---|---|
| `MODEL_ID` | A unique ID for the model endpoint that you defined. |

### `google_ml.list_model()` function

The following shows how to call the `google_ml.list_model()` SQL function used
to list model endpoint information:

```sql
  SELECT google_ml.list_model('MODEL_ID');
```

| Parameter | Description |
|---|---|
| `MODEL_ID` | A unique ID for the model endpoint that you defined. |

### `google_ml.model_info_view` view

The following shows how to call the `google_ml.model_info_view` view that is
used to list model endpoint information for all model endpoints:

```sql
  SELECT * FROM google_ml.model_info_view;
```

## Secrets

Use this reference to understand parameters for functions that let you manage
secrets.

### `google_ml.create_sm_secret()` function

The following shows how to call the `google_ml.create_sm_secret()` SQL function
used to add the secret created in Secret Manager:

```sql
    CALL
    google_ml.create_sm_secret(
      secret_id => 'SECRET_ID',
      secret_path => 'projects/project-id/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');
```

| Parameter | Description |
|---|---|
| `SECRET_ID` | The secret ID that you set and is subsequently used when registering a model endpoint. |
| `PROJECT_ID` | The ID of your Google Cloud project that contains the secret. This project can be different from the project that contains your AlloyDB cluster. |
| `SECRET_MANAGER_SECRET_ID` | The secret ID set in Secret Manager when you created the secret. |
| `VERSION_NUMBER` | The version number of the secret ID. |

### `google_ml.alter_sm_secret()` function

The following shows how to call the `google_ml.alter_sm_secret()` SQL function
used to update secret information:

```sql
  CALL
    google_ml.alter_sm_secret(
      secret_id => 'SECRET_ID',
      secret_path => 'projects/project-id/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');
```

For information about the values that you must set for each parameter, see [Create a secret](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#create-secret).

### `google_ml.drop_sm_secret()` function

The following shows how to call the `google_ml.drop_sm_secret()` SQL function
used to drop a secret:

```sql
  CALL google_ml.drop_sm_secret('SECRET_ID');
```

| Parameter | Description |
|---|---|
| `SECRET_ID` | The secret ID that you set and was subsequently used when registering a model endpoint. |

## Prediction functions

Use this reference to understand parameters for functions that let you generate
embeddings or invoke predictions.

### `google_ml.embedding()` function

For text embedding models without built-in support, the input and output
parameters are unique to a model and need to be transformed for the function to
call the model. You must create a transform input function to transform input of
the prediction function to the model specific input, and a transform output
function to transform model specific output to the prediction function
output.The function is also available in the `ai` schema

The following shows how to generate embeddings:

```sql
SELECT
  google_ml.embedding(
    model_id => 'MODEL_ID',
    content => 'CONTENT');
```

| Parameter | Description |
|---|---|
| `MODEL_ID` | A unique ID for the model endpoint that you define. |
| `CONTENT` | The text to translate into a vector embedding. |

For examples of SQL queries that generate text embeddings, see
[generate text embedding](https://docs.cloud.google.com/alloydb/docs/ai/work-with-embeddings.md.txt).

### `google_ml.predict_row()` function

The following shows how to invoke predictions that is used to call a registered
generic model endpoint, as long as the model supports a JSON-based API, to
invoke predictions. The function is also available in the `ai` schema:

```sql
SELECT
  google_ml.predict_row(
    model_id => 'MODEL_ID',
    request_body => 'REQUEST_BODY');
```

| Parameter | Description |
|---|---|
| `MODEL_ID` | A unique ID for the model endpoint that you define. |
| `REQUEST_BODY` | The parameters to the prediction function, in JSON format. |

For examples of SQL queries that invoke predictions, see [Examples](https://docs.cloud.google.com/alloydb/docs/ai/invoke-predictions.md.txt).

## Multimodal prediction functions

Use this reference to understand parameters for functions that let you generate multimodal embeddings.

AlloyDB reserves, and creates, the `ai` schema.

### `ai.text_embedding()`/`google_ml.text_embedding()` function

The following shows how to generate text embeddings:

```sql
SELECT
  ai.text_embedding(
    model_id => 'MODEL_ID',
    content => 'CONTENT');
```

| Parameter | Description |
|---|---|
| `MODEL_ID` | A unique ID for the model endpoint that you define. |
| `CONTENT` | The text to translate into a vector embedding. |

For examples of SQL queries that generate multimodal text embeddings, see
[Examples](https://docs.cloud.google.com/alloydb/docs/ai/generate-multimodal-embeddings.md.txt).

### `ai.image_embedding()`/`google_ml.image_embedding()` function

The following shows how to generate multimodal image embeddings:

> [!NOTE]
> **Note:** For API limits related to Agent Platform multimodal models, see [API
> limits](https://docs.cloud.google.com/gemini-enterprise-agent-platform/resources/agent-quotas).

```sql
SELECT
  ai.image_embedding(
    model_id => 'MODEL_ID',
    image => 'IMAGE_PATH_OR_TEXT',
    mimetype => 'MIMETYPE');
```

| Parameter | Description |
|---|---|
| `MODEL_ID` | A unique ID for the model endpoint that you define. |
| `IMAGE_PATH_OR_TEXT` | The Cloud Storage path to the image to translate into a vector embedding or base64 string of the image. |
| `MIMETYPE` | The mimetype of the image. |

For examples of SQL queries that generate multimodal image embeddings, see
[Examples](https://docs.cloud.google.com/alloydb/docs/ai/generate-multimodal-embeddings.md.txt).

### `ai.video_embedding()`/`google_ml.video_embedding()` function

The following shows how to generate multimodal video embeddings:

> [!NOTE]
> **Note:** For API limits related to Agent Platform multimodal models, see [API
> limits](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/multimodal-embeddings-api#api-limits).

```sql
SELECT
  ai.video_embedding(
    model_id => 'MODEL_ID',
    video => 'VIDEO_URI',
    start_offset_seconds => 'START_OFFSET_SEC',
    end_offset_seconds => 'END_OFFSET_SEC',
    interval_seconds => 'INTERVAL_SEC');
```

| Parameter | Description |
|---|---|
| `MODEL_ID` | A unique ID for the model endpoint that you define. |
| `VIDEO_URI` | The Cloud Storage URI of the target video to get embeddings for. For example,`gs://my-bucket/embeddings/supermarket-video.mp4`. |
| `START_OFFSET_SEC` | Offset timing to start processing video from. |
| `END_OFFSET_SEC` | Offset timing to stop processing video from. |
| `INTERVAL_SEC` | Interval seconds for which the embedding is generated. |

For examples of SQL queries that generate multimodal video embeddings, see
[Examples](https://docs.cloud.google.com/alloydb/docs/ai/generate-multimodal_embeddings).

## Ranking functions

Use this reference to understand parameters for functions that let you rank search results.

AlloyDB reserves, and creates, the `ai` schema.

### `ai.rank()/google_ml.rank()` function

The `ai.rank()` function supports two operations: ranking documents by using
the Agent Platform Ranking API or scoring
items based on a semantic prompt to an LLM such as Gemini.

> [!NOTE]
> **Note:** For API limits related to Agent Platform ranking models, see [Rank (or rerank) a set of records according to a query](https://docs.cloud.google.com/generative-ai-app-builder/docs/ranking.md.txt#rank_or_rerank_a_set_of_records_according_to_a_query).

#### Ranking search results with the Ranking API

This mode ranks and scores candidate documents against a search query by using
a semantic-ranker model provided by the
Agent Platform Ranking API.

```sql
SELECT *
FROM
  ai.rank(
    model_id => 'MODEL_ID',
    search_string => 'SEARCH_STRING',
    documents => ARRAY['DOCUMENT_1', 'DOCUMENT_2', 'DOCUMENT_3'],
    top_n => TOP_N); -- Optional
```

| Parameter | Description |
|---|---|
| `MODEL_ID` | The ranking model to use, such as `semantic-ranker-default-003`, `semantic-ranker-512`, or the unique ID of a registered ranking model endpoint. |
| `SEARCH_STRING` | The search query against which the candidate documents are ranked and scored. |
| `DOCUMENT_1, DOCUMENT_2, DOCUMENT_3` | The candidate document strings to rank and score against the search query, passed as elements of a PostgreSQL text array (`text[]`). |
| `TOP_N` (Optional) | The number of top results to return. If omitted or set to `NULL`, the function returns all ranked documents. |

The `ai.rank()` function returns a table that contains the following columns:

- The `index` column (`integer`): The 1-based index corresponding to the position of the document in the input `documents` array.
- The `score` column (`real`): The relevance score assigned to the document. A higher score indicates greater relevance to the search query.

For examples of SQL queries that generate ranked search results, see
[Rank search results](https://docs.cloud.google.com/alloydb/docs/ai/rank-rerank-search-results-rag.md.txt).

#### LLM-based ranking

This mode scores items based on a prompt specified in natural language by using
an LLM such as Gemini. It supports scalar, batch (array-based), and
cursor-based processing. The scalar version returns a `real` value:

```sql
SELECT
  ai.rank(
    model_id => 'MODEL_ID', -- Optional
    prompt => 'PROMPT');
```

| Parameter | Description |
|---|---|
| `MODEL_ID` (Optional) | A Gemini model ID or a unique ID for a model endpoint that you define. If not set, the default Gemini model is used. |
| `PROMPT` | The natural language phrase that specifies the criteria for scoring the item. For example, `Score the following review according to these rules: score of 8 to 10 if the review says the food is excellent, 4 to 7 if the review says the food is good, and 1 to 3 if the review says the food is not good. Here is the review:` |

For examples of SQL queries that score items by using natural language, or to
see batch (array-based) and cursor-based versions, see
[`ai.rank()` and `google_ml.rank()` operator functions](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt#ai-score) and
[Score your query results](https://docs.cloud.google.com/alloydb/docs/ai/evaluate-semantic-queries-ai-operators.md.txt#score-query-results).

## Operator functions

Use this reference to understand parameters for functions provided by the
AI functions that let you interact with data in your
database using natural language in SQL operators.

AlloyDB reserves, and creates, the `ai` schema.

### `ai.if()/google_ml.if()` function

The following shows how to perform filters and joins to evaluate a condition.

#### Scalar version

```sql
SELECT
  ai.if(
    model_id => 'MODEL_ID',
    prompt => 'PROMPT');
```

| Parameter | Description |
|---|---|
| `MODEL_ID` (Optional) | A unique ID for the model endpoint that you define. If not set, the default Gemini model is used. |
| `PROMPT` | The natural language phrase that specifies the condition based on which the function retrieves information. For example, `the following review talks about parking at the restaurant. review:` |

#### Batch (array-based) version

```sql
SELECT
  ai.if(
    prompts => ARRAY['PROMPT_1', 'PROMPT_2'],
    batch_size => BATCH_SIZE, -- Optional
    model_id => 'MODEL_ID'); -- Optional
```

| Parameter | Description |
|---|---|
| `PROMPTS` | An array of natural language text inputs to evaluate. |
| `BATCH_SIZE` (Optional) | The batch size for processing. Default is `NULL`. |
| `MODEL_ID` (Optional) | A unique ID for the model endpoint that you define. If not set, default Gemini model is used. |

#### Cursor-based version

```sql
SELECT
  ai.if(
    prompt => 'PROMPT',
    input_cursor => INPUT_CURSOR,
    batch_size => BATCH_SIZE, -- Optional
    model_id => 'MODEL_ID'); -- Optional
```

| Parameter | Description |
|---|---|
| `PROMPT` | The natural language phrase that specifies the condition to evaluate for each record. |
| `INPUT_CURSOR` | A `REFCURSOR` pointing to the input text records. |
| `BATCH_SIZE` (Optional) | The batch size for processing. Default is `NULL`. |
| `MODEL_ID` (Optional) | A unique ID for the model endpoint that you define. If not set, default Gemini model is used. |

For examples of SQL queries that perform filters and joins to evaluate a condition, see
[Use natural language in SQL operators](https://docs.cloud.google.com/alloydb/docs/ai/evaluate-semantic-queries-ai-operators.md.txt).

### `ai.forecast()/google_ml.forecast()` function

The following examples demonstrate how to perform time-series predictions directly in your AlloyDB database:

- From a source table

  ```sql
  SELECT * FROM ai.forecast(
      model_id => 'MODEL_ID',
      source_table => 'SOURCE_TABLE',
      data_col => 'DATA_COL',
      timestamp_col => 'TIMESTAMP_COL',
      horizon => 'HORIZON',
      conf_level => 'CONF_LEVEL'
  );
  ```
- From a source query

  ```sql
  SELECT * FROM ai.forecast(
      model_id => 'MODEL_ID',
      source_query => 'SOURCE_QUERY',
      data_col => 'DATA_COL',
      timestamp_col => 'TIMESTAMP_COL',
      horizon => 'HORIZON',
      conf_level => 'CONF_LEVEL'
  );
  ```

| Parameter | Description |
|---|---|
| `MODEL_ID` | A unique identifier for the registered model you want to use for forecasting---for example, `vertex_timesfm`. |
| `SOURCE_TABLE` | The name of the table that contains the time-series data you want to forecast. Use either `SOURCE_TABLE` or `SOURCE_QUERY`---for example, `time_series_data`. |
| `SOURCE_QUERY` | A PostgreSQL `SELECT` statement that generates the time series data you want to forecast. Useful for filtering or transforming input data. Use either `SOURCE_TABLE` or `SOURCE_QUERY`---for example, `(SELECT * FROM forecast_3 ORDER BY timestamp LIMIT 1) AS time_series_data`. |
| `DATA_COL` | The name of the column in the source table or query that contains the data points to forecast. The name of the column in your source table or query that contains the numeric values to forecast. This column must contain more than one value---for example, `data_points`. |
| `TIMESTAMP_COL` | The name of the column in your source table or query that contains the time points for each data point. This column provides the temporal context for the forecast---for example, `timestamp`. |
| `HORIZON` | The number of future time steps to forecast. The valid input range is \[1, 128\]---for example, `2`. |
| `CONF_LEVEL` | The confidence level for the forecast. The valid input range is (0, 1). A higher value results in wider prediction intervals---for example, `0.80`. > [!NOTE] > **Note:** A `conf_level` of `0.80` means you can expect the actual future value to fall within the predicted interval 80% of the time. |

### `ai.rank()`/`google_ml.rank()` function

The following shows how to get a score for items in the query based on
semantic criteria specified in natural language:

For API limits related to Agent Platform ranking models, see
[Rank (or rerank) a set of records according to a query](https://docs.cloud.google.com/generative-ai-app-builder/docs/ranking.md.txt#rank_or_rerank_a_set_of_records_according_to_a_query).

#### Scalar version

```sql
SELECT
  ai.rank(
    model_id => 'MODEL_ID', -- Optional
    prompt => 'PROMPT');
```

| Parameter | Description |
|---|---|
| `MODEL_ID` (Optional) | A unique ID for the model endpoint that you define. If not set, the default Gemini model is used. |
| `PROMPT` | The natural language phrase that specifies the criteria based on which the function orders the documents. For example, `Score the following review according to these rules: score of 8 to 10 if the review says the food is excellent, 4 to 7 if the review says the food is and 1 to 3 if the review says the food is not good. Here is the review:` |

### `ai.generate()`/`google_ml.generate()` function

The following shows how to generate text using the default model:

#### Scalar version

```sql
SELECT
  ai.generate(
    model_id => 'MODEL_ID',
    prompt => 'PROMPT');
```

| Parameter | Description |
|---|---|
| `MODEL_ID` (Optional) | A unique ID for the model endpoint that you define. If not set, the default Gemini model is used. |
| `PROMPT` | The natural language phrase that specifies the criteria based on which the function generates text embeddings. For example, `Summarize the review in 20 words or less. Review:` |

#### Batch (array-based) version

```sql
SELECT
  ai.generate(
    prompts => ARRAY['PROMPT_1', 'PROMPT_2'],
    batch_size => BATCH_SIZE, -- Optional
    model_id => 'MODEL_ID'); -- Optional
```

| Parameter | Description |
|---|---|
| `PROMPTS` | An array of natural language text prompts to process. |
| `BATCH_SIZE` (Optional) | The batch size for processing. Default is `NULL`. |
| `MODEL_ID` (Optional) | A unique ID for the model endpoint that you define. If not set, default Gemini model is used. |

#### Cursor-based version

```sql
SELECT
  ai.generate(
    prompt => 'PROMPT',
    input_cursor => INPUT_CURSOR,
    batch_size => BATCH_SIZE, -- Optional
    model_id => 'MODEL_ID'); -- Optional
```

| Parameter | Description |
|---|---|
| `PROMPT` | A context prompt or instruction to guide the model for each record. |
| `INPUT_CURSOR` | A `REFCURSOR` pointing to the input text records. |
| `BATCH_SIZE` (Optional) | The batch size for processing. Default is `NULL`. |
| `MODEL_ID` (Optional) | A unique ID for the model endpoint that you define. If not set, default Gemini model is used. |

For examples of SQL queries that generate text using the default model, see
[Perform intelligent SQL queries using AI functions](https://docs.cloud.google.com/alloydb/docs/ai/evaluate-semantic-queries-ai-operators.md.txt).

### `ai.extract()`/`google_ml.extract()` function

> [!NOTE]
> **Note:** The `ai.extract` function is supported on PostgreSQL version 18 and later.

The following shows how to extract structured data from text or documents based on a specified schema:

**Scalar function**:

```sql
SELECT
  ai.extract(
    input => 'INPUT',
    output_schema => 'OUTPUT_SCHEMA',
    model_id => 'MODEL_ID');
```

**Array-based function**:

```sql
SELECT
  ai.extract(
    inputs => INPUTS,
    output_schema => 'OUTPUT_SCHEMA',
    batch_size => BATCH_SIZE,
    model_id => 'MODEL_ID');
```

**Cursor-based function**:

```sql
SELECT
  ai.extract(
    input_cursor => INPUT_CURSOR,
    output_schema => 'OUTPUT_SCHEMA',
    batch_size => BATCH_SIZE,
    model_id => 'MODEL_ID');
```

| Parameter | Description |
|---|---|
| `INPUT` | The natural language text or document from which to extract structured data. |
| `INPUTS` | An array of natural language text or document strings from which to extract structured data. |
| `INPUT_CURSOR` | A reference cursor (`REFCURSOR`) pointing to the input data query that you want to process. |
| `OUTPUT_SCHEMA` | A JSON or text specification describing the fields, data types, or structure to extract from the input. For example, `'{"contact_name": {"type": "string"}, "company_name": {"type": "string"}}'` |
| `BATCH_SIZE` (Optional) | The number of records or array items to process per batch. The default value is `10`. |
| `MODEL_ID` (Optional) | A unique ID for the model endpoint that you define. If you don't specify a model ID, then the function uses the default Gemini model. |

For examples of SQL queries that extract structured data from text or documents, see
[Extract structured data](https://docs.cloud.google.com/alloydb/docs/ai/extract-structured-data.md.txt).

### `ai.classify()`/`google_ml.classify()` function

> [!NOTE]
> **Note:** The `ai.classify` function is supported on PostgreSQL version 18 and later.

The following shows how to categorize text inputs into predefined classes:

**Scalar function**:

```sql
SELECT
  ai.classify(
    input => 'INPUT',
    categories => CATEGORIES,
    examples => 'EXAMPLES',
    output_mode => 'OUTPUT_MODE',
    model_id => 'MODEL_ID');
```

**Array-based function**:

```sql
SELECT
  ai.classify(
    inputs => INPUTS,
    categories => CATEGORIES,
    examples => 'EXAMPLES',
    output_mode => 'OUTPUT_MODE',
    batch_size => BATCH_SIZE,
    model_id => 'MODEL_ID');
```

**Cursor-based function**:

```sql
SELECT
  ai.classify(
    input_cursor => INPUT_CURSOR,
    categories => CATEGORIES,
    examples => 'EXAMPLES',
    output_mode => 'OUTPUT_MODE',
    batch_size => BATCH_SIZE,
    model_id => 'MODEL_ID');
```

| Parameter | Description |
|---|---|
| `INPUT` | The natural language text input to classify. |
| `INPUTS` | An array of natural language text inputs to classify. |
| `INPUT_CURSOR` | A reference cursor (`REFCURSOR`) pointing to the input data query that you want to classify. |
| `CATEGORIES` | A 2D array of strings (`TEXT[][]`) defining the target categories and optional descriptions. For example, `ARRAY[ARRAY['sports', 'Sports news'], ARRAY['technology', 'Tech news']]` or `ARRAY['sports', 'technology', 'finance']`. |
| `EXAMPLES` (Optional) | A multi-line string or JSON array of objects providing few-shot examples to guide the model. |
| `OUTPUT_MODE` (Optional) | Specifies the output format as either `'single'` (returns the single best matching category) or `'multi'` (returns a comma-separated list of all applicable categories). The default value is `'single'`. |
| `BATCH_SIZE` (Optional) | The number of records or array items to process per batch. The default value is `10`. |
| `MODEL_ID` (Optional) | A unique ID for the model endpoint that you define. If you don't specify a model ID, then the function uses the default Gemini model. |

For examples of SQL queries that categorize text inputs into predefined classes, see
[Classify text](https://docs.cloud.google.com/alloydb/docs/ai/classify-text.md.txt).

### `ai.analyze_sentiment()`/`google_ml.analyze_sentiment()` function

The `ai.analyze_sentiment` function is used to classify the sentiment of text as positive, negative, or neutral. It supports scalar, array-based (batch), and cursor-based processing.

#### Scalar version

```sql
SELECT
  ai.analyze_sentiment(
    input => 'TEXT_CONTENT',
    model_id => 'MODEL_ID'); -- Optional
```

| Parameter | Description |
|---|---|
| `TEXT_CONTENT` | The text content to analyze. |
| `MODEL_ID` (Optional) | A unique ID for the model endpoint that you define. If you don't specify a model ID, then the function uses the default Gemini model. |

#### Batch (array-based) version

```sql
SELECT
  ai.analyze_sentiment(
    inputs => ARRAY['TEXT_1', 'TEXT_2'],
    batch_size => BATCH_SIZE, -- Optional
    model_id => 'MODEL_ID'); -- Optional
```

| Parameter | Description |
|---|---|
| `INPUTS` | An array of text inputs to analyze. |
| `BATCH_SIZE` (Optional) | The batch size for processing. Default is 10. |
| `MODEL_ID` (Optional) | A unique ID for the model endpoint that you define. If you don't specify a model ID, then the function uses the default Gemini model. |

#### Cursor-based version

```sql
SELECT
  ai.analyze_sentiment(
    input_cursor => INPUT_CURSOR,
    batch_size => BATCH_SIZE, -- Optional
    model_id => 'MODEL_ID'); -- Optional
```

| Parameter | Description |
|---|---|
| `INPUT_CURSOR` | A `REFCURSOR` pointing to the input text records. |
| `BATCH_SIZE` (Optional) | The batch size for processing. Default is `NULL`. |
| `MODEL_ID` (Optional) | A unique ID for the model endpoint that you define. If not set, default Gemini model is used. |

### `ai.summarize()`/`google_ml.summarize()` function

The `ai.summarize` function is used to condense and rephrase text into its most essential form. It supports scalar, array-based (batch), and cursor-based processing.

#### Scalar version

```sql
SELECT
  ai.summarize(
    input => 'TEXT_CONTENT',
    additional_instructions => 'INSTRUCTIONS', -- Optional
    model_id => 'MODEL_ID'); -- Optional
```

| Parameter | Description |
|---|---|
| `TEXT_CONTENT` | The text content to summarize. |
| `MODEL_ID` (Optional) | A unique ID for the model endpoint that you define. If you don't specify a model ID, then the function uses the default Gemini model. |

#### Batch (array-based) version

```sql
SELECT
  ai.summarize(
    inputs => ARRAY['TEXT_1', 'TEXT_2'],
    additional_instructions => 'INSTRUCTIONS', -- Optional
    batch_size => BATCH_SIZE, -- Optional
    model_id => 'MODEL_ID'); -- Optional
```

| Parameter | Description |
|---|---|
| `PROMPTS` | An array of text inputs to summarize. |
| `BATCH_SIZE` (Optional) | The batch size for processing. Default is 10. |
| `MODEL_ID` (Optional) | A unique ID for the model endpoint that you define. If you don't specify a model ID, then the function uses the default Gemini model. |

#### Cursor-based version

```sql
SELECT
  ai.summarize(
    input_cursor => INPUT_CURSOR,
    additional_instructions => 'INSTRUCTIONS', -- Optional
    batch_size => BATCH_SIZE, -- Optional
    model_id => 'MODEL_ID'); -- Optional
```

| Parameter | Description |
|---|---|
| `INPUT_CURSOR` | A `REFCURSOR` pointing to the input text records. |
| `INSTRUCTIONS` (Optional) | Additional context or instruction to guide the model. |
| `BATCH_SIZE` (Optional) | The batch size for processing. Default is `NULL`. |
| `MODEL_ID` (Optional) | A unique ID for the model endpoint that you define. If not set, default Gemini model is used. |

### `ai.agg_summarize()`/`google_ml.agg_summarize()` function

The `ai.agg_summarize` function is an aggregate function that operates across multiple rows in a column, combining the text into a single unified prompt to generate one consolidated summary.

Because it is an aggregate function, it does not support named arguments. You
must call it using positional arguments.

Here are the supported signatures:

#### Signature 1: Summarize using the default model and no additional instructions

```sql
ai.agg_summarize(
  'COLUMN_NAME')
```

#### Signature 2: Summarize using the default model with additional instructions

```sql
ai.agg_summarize(
  'COLUMN_NAME',
  'INSTRUCTIONS')
```

#### Signature 3: Summarize using a specific model with additional instructions

```sql
ai.agg_summarize(
  'COLUMN_NAME',
  'INSTRUCTIONS',
  'MODEL_ID')
```

#### Signature 4: Summarize using a specific model and no additional instructions

To call this version, you must explicitly cast the `MODEL_ID` to `VARCHAR` to
distinguish it from `INSTRUCTIONS`.

```sql
ai.agg_summarize(
  'COLUMN_NAME',
  'MODEL_ID'::VARCHAR)
```

| Parameter | Description |
|---|---|
| `COLUMN_NAME` | The name of the text column containing the rows to aggregate and summarize. |
| `MODEL_ID` (Optional) | A unique ID for the model endpoint that you define. If you don't specify a model ID, then the function uses the default Gemini model. |

## Optimized AI functions

Use this reference to understand functions, procedures, and views provided by the
`google_ml_integration` extension to inspect, manage, and retrain proxy models for
optimized AI functions. For more information about using optimized AI functions to accelerate
queries, see [Accelerate queries using optimized functions](https://docs.cloud.google.com/alloydb/docs/ai/accelerate-queries-optimized-functions.md.txt).

> [!NOTE]
> **Note:** Optimized AI functions and views require version 1.6.3 or later of the `google_ml_integration` extension.

### `ai.if()`/`google_ml.if()` optimized function

The optimized `ai.if()` function (also accessible as `google_ml.if()`) evaluates a condition specified in natural language using vector embeddings and a locally trained proxy model, and returns a `BOOLEAN` value:

```sql
SELECT
  ai.if(
    prompt => 'PROMPT',
    embedding => EMBEDDING,
    llm_model_id => 'LLM_MODEL_ID'); -- Optional
```

    -- Function signature
    FUNCTION ai.if(
      prompt TEXT,
      embedding REAL[],
      llm_model_id VARCHAR(100) DEFAULT NULL)
    RETURNS BOOLEAN

| Parameter | Description |
|---|---|
| `PROMPT` | A `TEXT` expression that specifies the natural language condition to evaluate. |
| `EMBEDDING` | The vector embedding input (`REAL[]`, or `VECTOR` cast to `REAL[]`) corresponding to the source data column. |
| `LLM_MODEL_ID` (Optional) | The `VARCHAR(100)` model ID of the baseline LLM used for proxy model training and fallback. Default is `NULL`. |

### Database flags

The following table describes the database flags used to configure proxy models for optimized AI functions:

| Flag | Type | Default | Description |
|---|---|---|---|
| `google_ml_integration.enable_cost_optimized_ai_functions` | `Boolean` | `on` | Enables proxy models for optimized AI functions in AlloyDB. |
| `google_ml_integration.proxy_models_enable_accuracy_check` | `Boolean` | `off` | Controls whether runtime accuracy checks are performed before executing queries with proxy models. When set to `on`, AlloyDB evaluates a sample of rows against the baseline remote LLM to verify model accuracy. If validation fails, execution falls back to the remote LLM (subject to `google_ml_integration.proxy_models_enable_llm_fallback`). |
| `google_ml_integration.proxy_models_enable_llm_fallback` | `Boolean` | `on` | Controls fallback to the baseline remote LLM when a proxy model is untrained, in the process of training, or fails accuracy validation. When set to `off`, queries raise an error instead of calling the remote LLM, protecting against unexpected API costs. |
| `google_ml_integration.proxy_models_enable_online_training` | `Boolean` | `off` | Controls whether queries use online (blocking) training for untrained proxy models. When set to `on`, the initial query blocks and waits for background training to complete before returning results, avoiding remote LLM inference on the first execution. |
| `google_ml_integration.proxy_models_training_wait_timeout` | `Integer` | `60` | Specifies the maximum duration, in seconds, that a query blocks and waits for online training to complete when `google_ml_integration.proxy_models_enable_online_training` is `on`. Valid range is `0` to `3600`. |
| `google_ml_integration.proxy_models_retraining_interval_minutes` | `Integer` | `1440` (24 hours) | Specifies the interval, in minutes, between periodic background retraining runs for proxy models. Setting this flag to `0` disables periodic retraining. Valid range is `0` to `2147483647`. > [!NOTE] > **Note:** Periodic background auto-retraining requires instances with 32 or more vCPUs with default configuration settings. |
| `google_ml_integration.proxy_models_retraining_batch_size` | `Integer` | `1` | Specifies the number of proxy models retrained in a single iteration during periodic background retraining. Valid range is `1` to `10000`. |
| `google_ml_integration.proxy_models_f1_score_threshold` | `Real` | `0.95` | Specifies the F1 score threshold for runtime accuracy checks. If the F1 score evaluated during an accuracy check is less than this threshold, the proxy model is considered inaccurate and query execution falls back to the remote LLM (subject to `google_ml_integration.proxy_models_enable_llm_fallback`). Valid range is `0.0` to `1.0`. |
| `google_ml_integration.proxy_models_sampling_percentage` | `Real` | `5.0` | Percentage of rows sampled from the source table during proxy model training and runtime accuracy checks. Valid range is `0.1` to `100.0`. |
| `google_ml_integration.proxy_models_max_sampling_count` | `Integer` | `1000` | Maximum number of row samples evaluated during proxy model training and runtime accuracy checks. Valid range is `10` to `10000`. |

### `ai.optimized_functions_view` view

The `ai.optimized_functions_view` view (also accessible as `google_ml.optimized_functions_view`) lists all existing proxy models in the database along with their training status and metadata:

```sql
SELECT * FROM ai.optimized_functions_view;
```

The view provides the following columns:

| Column name | Data type | Description |
|---|---|---|
| `user_name` | `TEXT` | The database user or role that initiated the proxy model training. |
| `table_name` | `TEXT` | The name of the source table evaluated by the proxy model. |
| `content_expr` | `TEXT` | The text content expression evaluated by the AI function. |
| `embedding_column` | `VARCHAR(64)` | The name of the column storing vector embeddings for the model. |
| `llm_model_id` | `VARCHAR(100)` | The baseline LLM model ID used for training (for example, `gemini-3.5-flash-lite`). |
| `model_type` | `VARCHAR(64)` | The architecture type of the proxy model (for example, `logistic_regression`). |
| `last_trained_at` | `TIMESTAMPTZ` | The timestamp when the most recent model training completed. |
| `training_duration` | `INTERVAL` | The duration of the most recent model training run. |
| `times_trained` | `INTEGER` | The total number of times the proxy model has been trained. |
| `last_training_time_start` | `TIMESTAMPTZ` | The timestamp when the most recent model training started. |
| `status` | `TEXT` | The current operational status of the model: - `READY`: Model trained and active. - `UNTRAINED`: Training scheduled or in progress. - `RETRAINING_IN_PROGRESS`: Periodic or manual retraining underway. - `RETRAINING_FAILED`: Retraining run failed. |

### `google_ml.proxy_training_jobs` view

The `google_ml.proxy_training_jobs` view displays active background worker training jobs by querying `pg_stat_activity` for the `Cost Optimized AI Function Worker` application name:

```sql
SELECT pid, query_start, state, query
FROM google_ml.proxy_training_jobs;
```

If a training job is actively running in the background, this view returns the associated session details. If no training is in progress, the view returns zero rows.

### `ai.retrain_optimized_model()` function

The `ai.retrain_optimized_model()` function (also accessible as `google_ml.retrain_optimized_model()`) manually retrains a specific proxy model.

#### Retrain by model training parameters

```sql
SELECT ai.retrain_optimized_model(
  table_name => 'TABLE_NAME',
  embedding_column => 'EMBEDDING_COLUMN',
  content_expr => 'CONTENT_EXPR',
  llm_model_id => 'LLM_MODEL_ID'); -- Optional
```

| Parameter | Description |
|---|---|
| `TABLE_NAME` | The name of the table whose proxy model you want to retrain. |
| `EMBEDDING_COLUMN` | The column containing vector embeddings. |
| `CONTENT_EXPR` | The exact content expression used during model training. |
| `LLM_MODEL_ID` (Optional) | The model ID of the baseline LLM to use for retraining. Default is `NULL`. |

#### Retrain by model ID

```sql
SELECT ai.retrain_optimized_model(model_id => 'MODEL_ID');
```

| Parameter | Description |
|---|---|
| `MODEL_ID` | The unique identifier of the proxy model to retrain. You can find model IDs by querying `google_ml.proxy_models_expr_mapping`. |

### `ai.retrain_optimized_models()` function

The `ai.retrain_optimized_models()` function (also accessible as `google_ml.retrain_optimized_models()`) bulk retrains proxy models associated with a specific table:

```sql
SELECT ai.retrain_optimized_models(
  table_name => 'TABLE_NAME',
  embedding_column => 'EMBEDDING_COLUMN', -- Optional
  content_expr => 'CONTENT_EXPR', -- Optional
  llm_model_id => 'LLM_MODEL_ID'); -- Optional
```

| Parameter | Description |
|---|---|
| `TABLE_NAME` | The name of the table whose models to retrain. |
| `EMBEDDING_COLUMN` (Optional) | Filter to models using this embedding column. Default is `NULL`. |
| `CONTENT_EXPR` (Optional) | Filter to models using this content expression. Default is `NULL`. |
| `LLM_MODEL_ID` (Optional) | Filter to models using this baseline LLM ID. Default is `NULL`. |

### `ai.delete_optimized_model()` function

The `ai.delete_optimized_model()` function (also accessible as `google_ml.delete_optimized_model()`) deletes a specific proxy model. This operation requires `alloydbsuperuser` privileges (or permissions granted by an administrator):

```sql
SELECT ai.delete_optimized_model('MODEL_ID');
```

| Parameter | Description |
|---|---|
| `MODEL_ID` | The unique identifier of the proxy model to delete. You can find model IDs by querying `google_ml.proxy_models_expr_mapping`. |

### `ai.delete_all_optimized_models()` procedure

The `ai.delete_all_optimized_models()` procedure (also accessible as `google_ml.delete_all_optimized_models()`) deletes all proxy models in the database and stops background auto-retraining jobs. This operation requires `alloydbsuperuser` privileges (or permissions granted by an administrator):

```sql
CALL ai.delete_all_optimized_models();
```

## Transform functions

Use this reference to understand parameters for input and output transform
functions.

> [!NOTE]
> **Note:** You cannot use transform functions when registering a `generic` model endpoint.

### Input transform function

The following shows the signature for the prediction function for text embedding
model endpoints:

```sql
  CREATE OR REPLACE FUNCTION INPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), input_text TEXT) RETURNS JSON;
```

| Parameter | Description |
|---|---|
| `INPUT_TRANSFORM_FUNCTION` | The function to transform input of the corresponding prediction function to the model endpoint-specific input. |

### Output transform function

The following shows the signature for the prediction function for text embedding
model endpoints:

```sql
  CREATE OR REPLACE FUNCTION OUTPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), response_json JSON) RETURNS real[];
```

| Parameter | Description |
|---|---|
| `OUTPUT_TRANSFORM_FUNCTION` | The function to transform model endpoint-specific output to the prediction function output. |

### Transform functions example

To better understand how to create transform functions for your model endpoint,
consider a custom-hosted text embedding model endpoint that requires JSON input
and output.

The following example curl request creates embeddings based on the prompt and
the model endpoint:

```bash
  curl -m 100 -X POST https://cymbal.com/models/text/embeddings/v1 \
    -H "Content-Type: application/json"
    -d '{"prompt": ["AlloyDB Embeddings"]}'
```

The following example response is returned:

```json
[[ 0.3522231  -0.35932037  0.10156056  0.17734447 -0.11606089 -0.17266059
   0.02509351  0.20305622 -0.09787305 -0.12154685 -0.17313677 -0.08075467
   0.06821183 -0.06896557  0.1171584  -0.00931572  0.11875633 -0.00077482
   0.25604948  0.0519384   0.2034983  -0.09952664  0.10347155 -0.11935943
  -0.17872004 -0.08706985 -0.07056875 -0.05929353  0.4177883  -0.14381726
   0.07934926  0.31368294  0.12543282  0.10758053 -0.30210832 -0.02951015
   0.3908268  -0.03091059  0.05302926 -0.00114946 -0.16233777  0.1117468
  -0.1315904   0.13947351 -0.29569918 -0.12330773 -0.04354299 -0.18068913
   0.14445548  0.19481727]]
```

Based on this input and response, we can infer the following:

- The model expects JSON input through the `prompt` field. This field accepts an
  array of inputs. As the `google_ml.embedding()` function is a row level
  function, it expects one text input at a time. Thus,you need to create an
  input transform function that builds an array with a single element.

- The response from the model is an array of embeddings, one for each prompt
  input to the model. As the `google_ml.embedding()` function is a row level
  function, it returns single input at a time. Thus, you need to create an
  output transform function that can be used to extract the embedding from the
  array.

The following example shows the input and output transform functions that is
used for this model endpoint when it is registered with model endpoint management:

### input transform function

```sql
CREATE OR REPLACE FUNCTION cymbal_text_input_transform(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
LANGUAGE plpgsql
AS $$
DECLARE
  transformed_input JSON;
  model_qualified_name TEXT;
BEGIN
  SELECT json_build_object('prompt', json_build_array(input_text))::JSON INTO transformed_input;
  RETURN transformed_input;
END;
$$;
```

### output transform function

```sql
CREATE OR REPLACE FUNCTION cymbal_text_output_transform(model_id VARCHAR(100), response_json JSON)
RETURNS REAL[]
LANGUAGE plpgsql
AS $$
DECLARE
  transformed_output REAL[];
BEGIN
SELECT ARRAY(SELECT json_array_elements_text(response_json->0)) INTO transformed_output;
RETURN transformed_output;
END;
$$;
```

## HTTP header generation function

The following shows signature for the header generation function that can be
used with the `google_ml.embedding()` prediction function when registering other
text embedding model endpoints.

```sql
  CREATE OR REPLACE FUNCTION GENERATE_HEADERS(model_id VARCHAR(100), input_text TEXT) RETURNS JSON;
```

For the `google_ml.predict_row()` prediction function, the signature is as
follows:

```sql
CREATE OR REPLACE FUNCTION GENERATE_HEADERS(model_id TEXT, input JSON) RETURNS JSON;
```

| Parameter | Description |
|---|---|
| `GENERATE_HEADERS` | The function to generate custom headers. You can also pass the authorization header generated by the header generation function while registering the model endpoint. |

### Header generation function example

To better understand how to create a function that generates output in JSON key
value pairs that are used as HTTP headers, consider a custom-hosted text
embedding model endpoint.

The following example curl request passes the `version` HTTP header which is
used by the model endpoint:

```bash
  curl -m 100 -X POST https://cymbal.com/models/text/embeddings/v1 \
      -H "Content-Type: application/json" \
      -H "version: 2024-01-01" \
      -d '{"prompt": ["AlloyDB Embeddings"]}'
```

The model expects text input through the `version` field and returns the version
value in JSON format. The following example shows the header generation function
that is used for this text embedding model endpoint when it is registered with model
endpoint management:

```sql
CREATE OR REPLACE FUNCTION header_gen_fn(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
LANGUAGE plpgsql
AS $$
BEGIN
  RETURN json_build_object('version', '2024-01-01')::JSON;
END;
$$;
```

#### Header generation function using API Key

The following examples show how to set up authentication using the API key.

### embedding model

```sql
CREATE OR REPLACE FUNCTION header_gen_func(
  model_id VARCHAR(100),
  input_text TEXT
)
RETURNS JSON
LANGUAGE plpgsql
AS $$
#variable_conflict use_variable
BEGIN
  RETURN json_build_object('Authorization', 'API_KEY')::JSON;
END;
$$;
```

Replace the `API_KEY` with the API key of the model provider.

### generic model

```sql
CREATE OR REPLACE FUNCTION header_gen_func(
  model_id VARCHAR(100),
  response_json JSON
)
RETURNS JSON
LANGUAGE plpgsql
AS $$
#variable_conflict use_variable
DECLARE
transformed_output REAL[];
BEGIN
  -- code to add Auth token to API request
RETURN json_build_object('x-api-key', 'API_KEY', 'anthropic-version', '2023-06-01')::JSON;
END;
$$;
```

Replace the `API_KEY` with the API key of the model provider.

## Request URL generation

Use the request URL generation function to infer the request URLs for the model
endpoints with built-in support. The following shows the signature for this
function:

```sql
SELECT google_ml.generate_model_request_url(PROVIDER_ID, MODEL_TYPE, MODEL_QUALIFIED_NAME)
```

| Parameter | Description |
|---|---|
| `PROVIDER_ID` | The provider of the model URL that you want to generate. Set to one of the following: - `google` for Agent Platform model endpoints - `open_ai` for OpenAI model endpoints - `hugging_face` for Hugging Face model endpoints - `anthropic` for Anthropic model endpoints - `custom` for other providers |
| `MODEL_TYPE` | The model type. Set to one of the following: - `text_embedding` for text embedding model endpoints - `multimodal_embedding` for multimodal embedding model endpoints - `reranking` for ranking model endpoints - `generic` for all other model endpoints |
| `MODEL_QUALIFIED_NAME` | Set the model qualified name. |