The CREATE MODEL statement for remote models over open generative AI models

This document describes the CREATE MODEL statement for creating remote models in BigQuery over open text embedding (Preview) and text generation models deployed to Vertex AI. 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 a remote model, you can use it with the ML.GENERATE_EMBEDDING or ML.GENERATE_TEXT function, depending on the model type.

CREATE MODEL syntax

{CREATE MODEL | CREATE MODEL IF NOT EXISTS | CREATE OR REPLACE MODEL}
`project_id.dataset.model_name`
REMOTE WITH CONNECTION `project_id.region.connection_id`
OPTIONS(ENDPOINT = vertex_ai_https_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 not 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 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_https_endpoint

Description

For vertex_ai_https_endpoint, specify the shared public endpoint of a model deployed to Vertex AI, in the format https://location-aiplatform.googleapis.com/v1/projects/project/locations/location/endpoints/endpoint_id. Dedicated public endpoints, Private Service Connect endpoints, and private endpoints aren't supported.

The following example shows how to create a remote model that uses a shared public endpoint:

ENDPOINT = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/endpoints/1234'

Supported open models

You can create a remote model over a deployed open model from either the Vertex AI Model Garden or Hugging Face.

Supported Vertex AI Model Garden models

The following open text generation models in the Vertex AI Model Garden are supported:

• Gemma 3
• Gemma 2
• CodeGemma
• TxGemma
• DeepSeek R1
• DeepSeek V3
• Llama 4
• Llama 3.3
• Llama 3.2
• Llama 3.1
• Llama Guard
• Llama 3
• Llama 2
• Llama 2 (Quantized)
• Code Llama
• Mistral Self-host (7B & Nemo)
• Mixtral
• Falcon-instruct (PEFT)
• Phi-4
• Phi-3
• QwQ
• Qwen2
• Vicuna

The following open embedding generation models in the Vertex AI Model Garden are supported:

• E5 Text Embedding (Preview)

Supported Hugging Face models

BigQuery ML supports Hugging Face models that use the Text Embeddings Inference API or the Text Generation Inference API and can be deployed to Vertex AI.

If you use the Vertex AI API to deploy the open model as a Vertex AI endpoint, you don't have to check whether the model has been verified by Vertex AI. Otherwise, you must verify that the model is supported before deploying it.

To find supported Hugging Face models, do the following:

1. On Hugging Face, open the list of Text Embeddings Inference or Text Generation Inference models, depending on the type of model that you want to create.
2. Locate a model that you are interested in and copy the model ID.
3. Open the Vertex AI Model Garden.
4. Click Deploy from Hugging Face.
5. On the Deploy from Hugging Face pane, paste the model ID into the Hugging Face URL field.

6. Press Enter.

   A green check circle is shown if the model can be deployed in Vertex AI Model Garden:

   

Deploy open models

Use the following instructions to deploy an open model to Vertex AI so that you can then reference it from a remote model.

Deploy Vertex AI Model Garden models

To deploy an open model from the Model Garden, do the following:

1. Go to Model Garden.

   Go to Model Garden

2. Locate the model's model card in the Model Garden and click it.

3. Use one of the deployment options on the model card. All models have a Deploy option for deploying directly, and an Open Notebook option for deploying the model by using a Colab Enterprise notebook. Some models also offer a Fine-Tune option for deploying a fine-tuned version of the model.

4. Follow the workflow of the deployment option that you have chosen. You must select Public (shared endpoint) as the value for the Endpoint access field in the deployment workflow. For more information, see Use models in Model Garden.

Deploy Hugging Face models

To deploy a Hugging Face text embedding (Preview) or text generation model, do the following:

To stop billing for a model, undeploy the model.

As an alternative to using the UI or a notebook, you can also use the Vertex AI API to deploy the open model as a Vertex AI endpoint.

Locations

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

Limitations

You can only use open models to process text data. Multimodal data isn't supported.

Example

The following example creates a BigQuery ML remote model over a model deployed to a Vertex AI endpoint:

CREATE MODEL `project_id.mydataset.mymodel`
 REMOTE WITH CONNECTION `myproject.us.test_connection`
 OPTIONS(ENDPOINT = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/endpoints/1234')

What's next

• Try generating text using your data.
• Try generating embeddings using your data.
• For more information about the supported SQL statements and functions for remote models that use HTTPS endpoints, see End-to-end user journey for each model.