Invoke predictions

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.

To invoke predictions, select one of the following schemas.

Before you begin

To let AlloyDB invoke predictions, do the following:

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:

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:

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.

For examples, see Example invocations.

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:

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:

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

For information about the model's JSON response messages, see PredictResponse.

Example invocations

The following example uses gemini-3.5-flash-lite, available in Model Garden, to generate text based on a short prompt that is provided as a literal argument to ml_predict_row():

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.

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

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

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:

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:

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.

What's next