The `google_ml_integration` extension in AlloyDB for PostgreSQL lets you invoke
online predictions from machine learning models directly in your SQL queries.
You can call the `ml_predict_row()` function in the `public` schema for generic
models hosted in Gemini Enterprise Agent Platform without registering
an endpoint, or call the `google_ml.predict_row()` function in the `google_ml`
schema for models
[registered with Model endpoint management](https://docs.cloud.google.com/alloydb/docs/ai/register-model-endpoint.md.txt).

To invoke predictions, select one of the following schemas.
<button value="public" default="">public schema</button> <button value="google_ml">google_ml schema</button>

> [!NOTE]
> **Note:** AlloyDB doesn't charge for AI function calls. However, when you call Gemini Enterprise Agent Platform, third-party, or self-hosted models and services (such as for hybrid search) from your database, the model or infrastructure provider charges you directly. For more information about Gemini Enterprise Agent Platform costs, see [Pricing](https://cloud.google.com/products/gemini-enterprise-agent-platform/pricing).

## Before you begin

To let AlloyDB invoke predictions, do the following:

- You can invoke predictions in regions where generative AI on Agent Platform is available. For a list of regions, see [Deployments and endpoints](https://docs.cloud.google.com/gemini-enterprise-agent-platform/resources/locations.md.txt).
- [Connect to your database using `psql`](https://docs.cloud.google.com/alloydb/docs/connect-psql.md.txt) or AlloyDB Studio.
- [Verify that the `google_ml_integration` extension is installed](https://docs.cloud.google.com/alloydb/docs/ai/configure-vertex-ai.md.txt#verify-installed-extension).
- [Verify that 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).
- Before you can invoke predictions from an AlloyDB database, you must configure AlloyDB to work with Agent Platform. For more information, see [Integrate your database with Agent Platform](https://docs.cloud.google.com/alloydb/docs/ai/configure-vertex-ai.md.txt).
- You must have an active Agent Platform model with an active endpoint that you have Identity and Access Management (IAM) permission to access. AlloyDB doesn't support private endpoints for getting online predictions.
- Grant permissions for database users to execute the prediction function to invoke predictions:

  ```sql
  \c DB_NAME
  GRANT EXECUTE ON FUNCTION ml_predict_row TO USER_NAME;
  ```

  <br />

  Replace the following:
  - `DB_NAME`: the name of the database on which the
    permissions should be granted

  - `USER_NAME`: the name of the user for whom the
    permissions should be granted

## Invoke online predictions

Use the `ml_predict_row()` SQL function to invoke online predictions
against your data.

The format of the function's initial argument depends on whether the ML model that you
want to use is in Model Garden or is an endpoint
running in a Google Cloud project.

### Use a model in Model Garden

To invoke an online prediction using an ML model that's running in the
Model Garden, use the following syntax for the `ml_predict_row()` SQL function:

```sql
SELECT ml_predict_row('projects/PROJECT_ID/locations/REGION_ID/publishers/google/models/MODEL_ID', '{ CONTENTS }');
```

Replace the following:

- `PROJECT_ID`: the ID of your Google Cloud project

- `REGION_ID`: the ID of the Google Cloud region or endpoint location that the model is
  located in---for example, `global` for `gemini-3.5-flash-lite`, or a supported region such as `us-central1`

- `MODEL_ID`: the ID of the ML model to use, including the method suffix (`:generateContent` or `:streamGenerateContent`) for Gemini models---for example, `gemini-3.5-flash-lite:generateContent` or `gemini-3.5-flash-lite:streamGenerateContent`

- `CONTENTS`: the inputs to the prediction call, in JSON format---for example, `"contents": [{"role": "user", "parts": [{"text": "..."}]}]` for Gemini models, or `"instances": [...]` for other Agent Platform models

If the ML model is stored in the same project and region as your AlloyDB cluster,
then you can abbreviate this function's first argument:

```sql
SELECT ml_predict_row('publishers/google/models/MODEL_ID', '{ CONTENTS }');
```

For information about the model's JSON response messages, see [Generative AI foundational model reference](https://docs.cloud.google.com/gemini-enterprise-agent-platform/reference/models/inference.md.txt).

For examples, see [Example invocations](https://docs.cloud.google.com/alloydb/docs/ai/invoke-predictions.md.txt#examples).

### Use a Agent Platform model endpoint

To invoke an online prediction using a Agent Platform model endpoint, use the following syntax for the `ml_predict_row()` SQL function:

```sql
SELECT ml_predict_row('projects/PROJECT_ID/locations/REGION_ID/endpoints/ENDPOINT_ID', '{ CONTENTS }');
```

Replace the following:

- `PROJECT_ID`: the ID of the Google Cloud project that the model is
  located in

- `REGION_ID`: the ID of the Google Cloud region the model is
  located in---for example, `us-central1`

- `ENDPOINT_ID`: the ID of the model endpoint

- `CONTENTS`: the inputs to the prediction call, in JSON format

If the endpoint is located in the same project and region as your AlloyDB cluster,
then you can abbreviate this function's first argument:

```sql
SELECT ml_predict_row('endpoints/ENDPOINT_ID', '{ CONTENTS }');
```

For information about the model's JSON response messages, see [PredictResponse](https://docs.cloud.google.com/gemini-enterprise-agent-platform/reference/rest/v1/projects.locations.endpoints/predict.md.txt#body.response_body).

### Example invocations

The following example uses [gemini-3.5-flash-lite](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/google-models.md.txt), available in Model Garden, to generate text based on a short prompt that is provided as a literal argument
to `ml_predict_row()`:

```sql
SELECT
  json_array_elements(ml_predict_row('publishers/google/models/gemini-3.5-flash-lite:streamGenerateContent',
      '{ "contents": [ { "role": "user", "parts": [ { "text": "For TPCH database schema as mentioned here https://www.tpc.org/TPC_Documents_Current_Versions/pdf/TPC-H_v3.0.1.pdf , generate a SQL query to find all supplier names which are located in the India nation."
} ] } ] }'))-> 'candidates' -> 0 -> 'content' -> 'parts' -> 0 -> 'text';
```

The response is a JSON object. For more information about the format of the object,
see [Response body](https://docs.cloud.google.com/gemini-enterprise-agent-platform/reference/models/inference.md.txt#response).

The following example modifies the previous example in the following ways:

- The example uses the contents of the current database's `messages.message` column as input.

- The example demonstrates the use of [the `json_build_object()` and `json_build_array()` functions](https://www.postgresql.org/docs/current/functions-json.html) as an aid to formatting the function parameters.

First, create a sample `messages` table if you don't already have one:

```sql
CREATE TABLE IF NOT EXISTS messages (message TEXT);
INSERT INTO messages (message) VALUES ('Why is the sky blue?');
```

Then invoke `ml_predict_row()` against the `messages` table:

```sql
SELECT
  ml_predict_row(
    'projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.5-flash-lite:generateContent',
    json_build_object(
      'contents',
      json_build_array(
        json_build_object(
          'role', 'user',
          'parts', json_build_array(
            json_build_object('text', message)
          )
        )
      )
    )
  )
FROM messages;
```

The returned JSON object contains a `candidates` array for every row in the `messages` table.

Because the response is a JSON object, you can pull specific fields from it using the PostgreSQL arrow operator:

```sql
SELECT
  ml_predict_row(
    'projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.5-flash-lite:generateContent',
    json_build_object(
      'contents',
      json_build_array(
        json_build_object(
          'role', 'user',
          'parts', json_build_array(
            json_build_object('text', message)
          )
        )
      )
    )
  ) -> 'candidates' -> 0 -> 'content' -> 'parts' -> 0 -> 'text'
FROM messages;
```

For more example arguments to `ml_predict_row()`, see [Quickstart using the Agent Platform API](https://docs.cloud.google.com/gemini-enterprise-agent-platform/agent-studio/quickstart.md.txt).

## What's next

- [Learn how to build a smart shopping assistant with AlloyDB, pgvector, and model endpoint management](https://codelabs.developers.google.com/smart-shop-agent-alloydb#0).
- Learn about the [model endpoint management reference](https://docs.cloud.google.com/alloydb/docs/reference/model-endpoint.md.txt).