The AI.GENERATE function

This document describes the AI.GENERATE function, which lets you analyze any combination of text and unstructured data from BigQuery standard tables. For each row in the table, the function generates a STRUCT that contains a STRING value.

The function works by sending requests to a Vertex AI Gemini model, and then returning that model's response.

You can use the AI.GENERATE function to perform tasks such as classification and sentiment analysis.

Prompt design can strongly affect the responses returned by the model. For more information, see Introduction to prompting.

Input

Using the AI.GENERATE function, you can use the following types of input:

Text data from standard tables.
ObjectRefRuntime values that are generated by the OBJ.GET_ACCESS_URL function. You can use ObjectRef values from standard tables as input to the OBJ.GET_ACCESS_URL function. (Preview)

When you analyze unstructured data, that data must meet the following requirements:

Content must be in one of the supported formats that are described in the Gemini API model mimeType parameter.
If you are analyzing a video, the maximum supported length is two minutes. If the video is longer than two minutes, AI.GENERATE only returns results based on the first two minutes.

Syntax

AI.GENERATE(
  [ prompt => ] 'prompt',
  connection_id => 'connection'
  [, endpoint => 'endpoint']
  [, model_params => model_params]
  [, output_schema => 'field_name1 data_type1, field_name2, data_type2, ...']
)

Arguments

AI.GENERATE takes the following arguments:

prompt: a STRING or STRUCT value that specifies the prompt to send to the model. The prompt must be the first argument that you specify. You can provide the prompt value in the following ways:

Specify a STRING value. For example, ('Write a poem about birds').

Specify a STRUCT value that contains one or more fields. You can use the following types of fields within the STRUCT value:

Field type	Description	Examples
`STRING`	A string literal, or the name of a `STRING` column.	String literal: `'Is Seattle a US city?'` String column name: `my_string_column`
`ARRAY<STRING>`	You can only use string literals in the array.	Array of string literals: `['Is ', 'Seattle', ' a US city']`
`ObjectRefRuntime`	An `ObjectRefRuntime` value returned by the `OBJ.GET_ACCESS_URL` function. The `OBJ.GET_ACCESS_URL` function takes an `ObjectRef` value as input, which you can provide by either specifying the name of a column that contains `ObjectRef` values, or by constructing an `ObjectRef` value. `ObjectRefRuntime` values must have the `access_url.read_url` and `details.gcs_metadata.content_type` elements of the JSON value populated.	Function call with `ObjectRef` column: `OBJ.GET_ACCESS_URL(my_objectref_column, 'r')` Function call with constructed `ObjectRef` value: `OBJ.GET_ACCESS_URL(OBJ.MAKE_REF('gs://image.jpg', 'myconnection'), 'r')`
`ARRAY<ObjectRefRuntime>`	`ObjectRefRuntime` values returned from multiple calls to the `OBJ.GET_ACCESS_URL` function. The `OBJ.GET_ACCESS_URL` function takes an `ObjectRef` value as input, which you can provide by either specifying the name of a column that contains `ObjectRef` values, or by constructing an `ObjectRef` value. `ObjectRefRuntime` values must have the `access_url.read_url` and `details.gcs_metadata.content_type` elements of the JSON value populated.	Function calls with `ObjectRef` columns: `[OBJ.GET_ACCESS_URL(my_objectref_column1, 'r'), OBJ.GET_ACCESS_URL(my_objectref_column2, 'r')]` Function calls with constructed `ObjectRef` values: `[OBJ.GET_ACCESS_URL(OBJ.MAKE_REF('gs://image1.jpg', 'myconnection'), 'r'), OBJ.GET_ACCESS_URL(OBJ.MAKE_REF('gs://image2.jpg', 'myconnection'), 'r')]`

The function combines STRUCT fields similarly to a CONCAT operation and concatenates the fields in their specified order. The same is true for the elements of any arrays used within the struct. The following table shows some examples of STRUCT prompt values and how they are interpreted:

Struct field types	Struct value	Semantic equivalent
`STRUCT<STRING>`	`('Describe the city of Seattle')`	'Describe the city of Seattle'
`STRUCT<STRING, STRING, STRING>`	`('Describe the city ', my_city_column, ' in 15 words')`	'Describe the city `my_city_column_value` in 15 words'
`STRUCT<STRING, ARRAY<STRING>>`	`('Describe ', ['the city of', 'Seattle'])`	'Describe the city of Seattle'
`STRUCT<STRING, ObjectRefRuntime>`	`('Describe this city', OBJ.GET_ACCESS_URL(image_objectref_column, 'r'))`	'Describe this city' `image`
`STRUCT<STRING, ObjectRefRuntime, ObjectRefRuntime>`	`('If the city in the first image is within the country of the second image, provide a ten word description of the city', OBJ.GET_ACCESS_URL(city_image_objectref_column, 'r'), OBJ.GET_ACCESS_URL(country_image_objectref_column, 'r'))`	'If the city in the first image is within the country of the second image, provide a ten word description of the city' `city_image` `country_image`

connection_id: a STRING value specifying the connection to use to communicate with the model, in the format [PROJECT_ID].[LOCATION].[CONNECTION_ID]. For example, myproject.us.myconnection.

Replace the following:
- PROJECT_ID: the project ID of the project that contains the connection.
- LOCATION: the location used by the connection. The connection must be in the same location as the dataset that contains the model.
- CONNECTION_ID: the connection ID—for example, myconnection.
  You can get this value by viewing 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 in Connection ID. For example, projects/myproject/locations/connection_location/connections/myconnection.
You need to grant the Vertex AI User role to the connection's service account in the project where you run the function.
endpoint: a STRING value that specifies the Vertex AI endpoint to use for the model. Only Gemini models are supported. If you specify the model name, BigQuery ML automatically identifies and uses the full endpoint of the model. If you don't specify an endpoint value, BigQuery ML selects a recent stable version of Gemini to use.
model_params: a JSON literal that provides additional parameters to the model. The model_params value must conform to the generateContent request body format. You can provide a value for any field in the request body except for the contents field; the contents field is populated with the prompt argument value.
output_schema: a STRING value that specifies the schema of the output, in the form field_name1 data_type1, field_name2 data_type2, .... Supported data types include STRING, INT64, FLOAT64, BOOL, ARRAY, and STRUCT.

For Gemini 1.5 models, only specify a FLOAT64 data type if you are certain that the return value won't be a round number. These models can sometimes return INT values rather than FLOAT values for round numbers, for example 2 instead of 2.0, and this can cause a parsing error in the query.

Output

AI.GENERATE returns a STRUCT value for each row in the table. The struct contains the following fields:

result: a STRING value containing the model's response to the prompt. The result is NULL if the request fails or is filtered by responsible AI. If you specify an output_schema then result is replaced by your custom schema.
full_response: a STRING value containing the JSON response from the projects.locations.endpoints.generateContent call to the model. The generated text is in the text element. The safety attributes are in the safety_ratings element.
status: a STRING value that contains the API response status for the corresponding row. This value is empty if the operation was successful.

Examples

The following examples assume that your connection and input tables are in your default project.

Describe cities

Suppose you have the following table called mydataset.cities with a single city column:

+---------+
| city    |
+---------+
| Seattle |
| Beijing |
| Paris   |
| London  |
+---------+

To generate a short description of each city, you can call the AI.GENERATE function and select the result field in the output by running the following query:

SELECT
  city,
  AI.GENERATE(
    ('Give a short, one sentence description of ', city),
    connection_id => 'us.test_connection',
    endpoint => 'gemini-2.0-flash').result
FROM mydataset.cities;

The result is similar to the following:

+---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+
|  city   |                                                                           result                                                                            |
+---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Seattle | Seattle is a vibrant city nestled between mountains and water, renowned for its coffee culture, tech industry, and rainy weather.                           |
| Beijing | Beijing is a vibrant metropolis where ancient history meets modern innovation, offering a captivating blend of cultural treasures and bustling urban life.  |
| Paris   | Paris is a romantic city renowned for its iconic landmarks, elegant architecture, and vibrant culture.                                                      |
| London  | London, a vibrant global metropolis brimming with history, culture, and innovation.                                                                         |
+---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+

Use structured output

Suppose you have the following table called mydataset.states with a single state column of US states:

+------------+
| state      |
+------------+
| Washington |
| Oregon     |
| California |
| Hawaii     |
+------------+

The following query generates state capitals for a list of states. The query uses the output_schema argument to set two custom fields in the output struct: state and capital.

SELECT
  state,
  AI.GENERATE(
    ('What is the capital of ', state, '?'),
    connection_id => 'us.example_connection',
    endpoint => 'gemini-2.0-flash',
    output_schema => 'state STRING, capital STRING').capital
FROM mydataset.states;

The result is similar to the following:

+------------+------------+
| state      | capital    |
+------------+------------+
| Washington | Olympia    |
| Oregon     | Salem      |
| California | Sacramento |
| Hawaii     | Honolulu   |
+------------+------------+

The following query shows how to set the model_params argument to specify a label for the request:

SELECT
  state,
  AI.GENERATE(
    ('What is the capital of ', state, '?'),
    connection_id => 'us.example_connection',
    endpoint => 'gemini-2.0-flash',
    model_params => JSON '{"labels":{"key": "my_key", "value": "useful_value"}}',
    output_schema => 'state STRING, capital STRING').capital
FROM mydataset.states;

Use `ObjectRefRuntime` input

Suppose you have the following table called mydataset.animals with a single STRUCT column that uses the ObjectRef format and contains images of animals:

+----------------------------+-----------------+--------------------+----------------------------------------------------------+
| animals.uri                | animals.version | animals.authorizer | animals.details                                          |
+----------------------------+-----------------+--------------------+----------------------------------------------------------+
| gs://mybucket/snake.jpeg   | 12345678        | us.conn            | {"gcs_metadata":{"content_type":"image/jpeg","md5_hash"… |
+----------------------------+-----------------+--------------------+----------------------------------------------------------+
| gs://mybucket/horse.bmp    | 23456789        | us.conn            | {"gcs_metadata":{"content_type":"image/bmp","md5_hash"…  |
+----------------------------+-----------------+--------------------+----------------------------------------------------------+
| gs://mybucket/spider.jpeg  | 234567890       | us.conn            | {"gcs_metadata":{"content_type":"image/jpeg","md5_hash"… |
+----------------------------+-----------------+--------------------+----------------------------------------------------------+

To generate a description of each animal, call the AI.GENERATE function and select the result field in the output by running the following query:

SELECT
  AI.GENERATE(('Describe ', OBJ.GET_ACCESS_URL(animals, 'r'), ' in ten words or less'),
  connection_id => 'us.test_connection',
  endpoint => 'gemini-2.0-flash').result
FROM mydataset.animals;

The result is similar to the following:

+---------------------------------------------------+
| result                                            |
+---------------------------------------------------+
| A green snake coiled on a tree branch             |
| A black horse standing near a fence               |
| A small yellow spider hiding under a flower petal |
+---------------------------------------------------+

Use Google search grounding

The following query shows how to set the model_params argument to use Google search grounding for the request. You can only use Google search grounding with Gemini 2.0 or later models.

SELECT
  name,
  AI.GENERATE(
    ('Please check the weather of ', name, ' for today.'),
    connection_id => 'us.test_connection',
    endpoint => 'gemini-2.0-flash-001',
    model_params => JSON '{"tools": [{"googleSearch": {}}]}'
  )
FROM UNNEST(['Seattle', 'NYC', 'Austin']) AS name

Locations

You can run AI.GENERATE in all of the regions that support Gemini models, and also in the US and EU multi-regions.

Quotas

See Vertex AI and Cloud AI service functions quotas and limits.

What's next

For more information about using Vertex AI models to generate text and embeddings, see Generative AI overview.
For more information about using Cloud AI APIs to perform AI tasks, see AI application overview.

The AI.GENERATE function

Input

Syntax

Arguments

Output

Examples

Describe cities

Use structured output

Use ObjectRefRuntime input

Use Google search grounding

Locations

Quotas

What's next

Use `ObjectRefRuntime` input