The CREATE MODEL statement for Vertex AI LLMs as MaaS

This document describes the CREATE MODEL statement for creating remote models in BigQuery over LLMs in Vertex AI as a model as a service (MaaS) by using SQL. When you use MaaS on Vertex AI, you don't have to provision or manage serving infrastructure for your models. Choose MaaS for rapid development and prototyping, when you want to minimize operational overhead. Vertex AI offers access to Google models, partner models and open models using MaaS. For more information, see When to use MaaS.

Alternatively, you can use the Google Cloud console user interface to create a model by using a UI (Preview) instead of constructing the SQL statement yourself.

After you create the remote model, you can use one of the following functions to perform generative AI with that model:

• AI.GENERATE_TEXT
• AI.GENERATE_TABLE (only for Gemini models)

CREATE MODEL syntax

{CREATE MODEL | CREATE MODEL IF NOT EXISTS | CREATE OR REPLACE MODEL}
`project_id.dataset.model_name`
REMOTE WITH CONNECTION {DEFAULT | `project_id.region.connection_id`}
OPTIONS(ENDPOINT = 'vertex_ai_llm_endpoint');

CREATE MODEL

Creates and trains a new model in the specified dataset. If the model name exists, CREATE MODEL returns an error.

CREATE MODEL IF NOT EXISTS

Creates and trains a new model only if the model doesn't exist in the specified dataset.

CREATE OR REPLACE MODEL

Creates and trains a model and replaces an existing model with the same name in the specified dataset.

model_name

The name of the model you're creating or replacing. The model name must be unique in the dataset: no other model or table can have the same name. The model name must follow the same naming rules as a BigQuery table. A model name can:

• Contain up to 1,024 characters
• Contain letters (upper or lower case), numbers, and underscores

model_name is case-sensitive.

If you don't have a default project configured, then you must prepend the project ID to the model name in the following format, including backticks:

`[PROJECT_ID].[DATASET].[MODEL]`

For example, `myproject.mydataset.mymodel`.

REMOTE WITH CONNECTION

Syntax

`[PROJECT_ID].[LOCATION].[CONNECTION_ID]`

BigQuery uses a Cloud resource connection to interact with the Vertex AI endpoint.

The connection elements are as follows:

• 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.

  To find your connection ID, view the connection details in the Google Cloud console. The connection ID is 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.

  To use a default connection, specify DEFAULT instead of the connection string containing PROJECT_ID.LOCATION.CONNECTION_ID.

If you are creating a remote model over a Vertex AI model that uses supervised tuning, you need to grant the Vertex AI Service Agent role to the connection's service account in the project where you create the model. Otherwise, you need to grant the Vertex AI User role to the connection's service account in the project where you create the model.

If you are using the remote model to analyze unstructured data from an object table, you must also grant the Vertex AI Service Agent role to the service account of the connection associated with the object table. You can find the object table's connection in the Google Cloud console, on the Details pane for the object table.

Example

`myproject.us.my_connection`

ENDPOINT

Syntax

ENDPOINT = 'vertex_ai_llm_endpoint'

Description

The Vertex AI endpoint for the remote model to use. You can specify the name of the Vertex AI model, for example gemini-2.5-flash, or you can specify the Vertex AI model's endpoint URL, for example https://europe-west6-aiplatform.googleapis.com/v1/projects/myproject/locations/europe-west6/publishers/google/models/gemini-2.5-flash. If you specify the model name, BigQuery ML automatically identifies and uses the full endpoint of the Vertex AI model based on the location of the dataset in which you create the model.

Arguments

A STRING value that contains the model name of the target Vertex AI LLM. The following LLMs are supported:

Pretrained Gemini models

All of the generally available and preview Gemini models are supported.

Note: To provide feedback or request support for the models in preview, send an email to [e-mail].

For supported Gemini models, you can specify the global endpoint, as shown in the following example:

  https://aiplatform.googleapis.com/v1/projects/test-project/locations/global/publishers/google/models/gemini-2.5-flash

Using the global endpoint for your requests can improve overall availability while reducing resource exhausted (429) errors, which occur when you exceed your quota for a regional endpoint. If you want to use Gemini in a region where it isn't available, you can avoid migrating your data to a different region by using the global endpoint instead. You can only use the global endpoint with the AI.GENERATE_TEXT function.

Note: Don't use the global endpoint if you have requirements for the data processing location, because when you use the global endpoint, you can't control or know the region where your processing requests are handled.

Note: Using Gemini 2.5 models with any of these functions incurs charges for the thinking process. With some functions, you can set a budget for the thinking process for Gemini 2.5 Flash and Gemini 2.5 Flash-Lite models. You can't set a budget for Gemini 2.5 Pro models. See the documentation for a given function for details.

Claude models

The following Anthropic Claude models are supported:

• claude-haiku-4-5@20251001
• claude-sonnet-4-5@20250929
• claude-opus-4-1@20250805
• claude-opus-4@20250514
• claude-sonnet-4@20250514
• claude-3-7-sonnet@20250219
• claude-3-5-haiku@20241022
• claude-3-haiku@20240307

You must enable Claude models in Vertex AI before you can use them. For more information, see Enable a partner model.

Although Claude models are multimodal, you can only use text input with Claude models in BigQuery ML.

After you create a remote model based on a Claude model, you can use the model with the AI.GENERATE_TEXT function to generate text based on a prompt you provide in a query or from a column in a standard table.

Mistral AI models

The following Mistral AI models are supported:

• mistral-large-2411
• mistral-nemo
• mistral-small-2503

Don't use a version suffix with any Mistral AI model.

You must enable Mistral AI models in Vertex AI before you can use them. For more information, see Enable a partner model.

After you create a remote model based on a Mistral AI model, you can use the model with the AI.GENERATE_TEXT function to generate text based on a prompt you provide in a query or from a column in a standard table.

Llama models as MaaS

To create a Llama model in BigQuery ML, you must specify it as an OpenAI API endpoint in the format openapi/<publisher_name>/<model_name>.

The following Llama models are supported:

• Llama 4 Scout 17B-16E, endpoint meta/llama-4-scout-17b-16e-instruct-maas
• Llama 4 Maverick 17B-128E, endpoint meta/llama-4-maverick-17b-128e-instruct-maas
• Llama 3.3 70B (Preview), endpoint openapi/meta/llama-3.3-70b-instruct-maas
• Llama 3.2 90B (Preview), endpoint openapi/meta/llama-3.2-90b-vision-instruct-maas
• Llama 3.1 405B (GA), endpoint openapi/meta/llama-3.1-405b-instruct-maas
• Llama 3.1 70B (Preview), endpoint openapi/meta/llama-3.1-70b-instruct-maas
• Llama 3.1 8B (Preview), endpoint openapi/meta/llama-3.1-8b-instruct-maas

Important: For Llama 4.0 and greater models, you must create the dataset and connection for the remote model in the same region as the Llama model endpoint.

You must enable Llama models in Vertex AI before you can use them. For more information, see Enable a partner model.

After you create a remote model based on a Llama model, you can use the model with the AI.GENERATE_TEXT function to generate text based on a prompt you provide in a query or from a column in a standard table.

For information that can help you choose between the supported models, see Model information.

Locations

For information about supported locations, see Locations for remote models.

Examples

The following examples create BigQuery ML remote models.

Create a Gemini model that uses the default connection

The following example creates a BigQuery ML remote model over a Gemini model:

CREATE OR REPLACE MODEL `mydataset.gemini_model`
REMOTE WITH CONNECTION DEFAULT
OPTIONS(ENDPOINT = 'gemini-2.5-flash');

Create a partner model that uses the default connection

The following example creates a BigQuery ML remote model over a Mistral AI model:

CREATE OR REPLACE MODEL `mydataset.mistral_model`
REMOTE WITH CONNECTION DEFAULT
OPTIONS(ENDPOINT = 'mistral-large-2411');

What's next

• For more information about using Vertex AI models with BigQuery ML, see Generative AI overview.
• Try generating text from BigQuery data.
• Try generating structured text from BigQuery data.