Generate text embeddings by using the AI.GENERATE_EMBEDDING function
This document shows you how to create a BigQuery MLremote modelthat references an embedding model. You then use that model with theAI.GENERATE_EMBEDDING functionto create text embeddings by using data from a BigQuerystandard table.
The following types of remote models are supported:
Required roles
To create a remote model and use theAI.GENERATE_EMBEDDING function, youneed the following Identity and Access Management (IAM) roles:
- Create and use BigQuery datasets, tables, and models:BigQuery Data Editor (
roles/bigquery.dataEditor) on your project. Create, delegate, and use BigQuery connections:BigQuery Connections Admin (
roles/bigquery.connectionsAdmin) on yourproject.If you don't have adefault connectionconfigured, you can create and set one as part of running the
CREATE MODELstatement. To do so, you must have BigQuery Admin(roles/bigquery.admin) on your project. For more information, seeConfigure the default connection.Grant permissions to the connection's service account: Project IAM Admin(
roles/resourcemanager.projectIamAdmin) on the project that contains theVertex AI endpoint. This is the current project for remote modelsthat you create by specifying the model name as an endpoint. This is theproject identified in the URL for remote models that you create byspecifying a URL as an endpoint.Create BigQuery jobs: BigQuery Job User(
roles/bigquery.jobUser) on your project.
These predefined roles contain the permissions required to perform the tasks inthis document. To see the exact permissions that are required, expand theRequired permissions section:
Required permissions
- Create a dataset:
bigquery.datasets.create - Create, delegate, and use a connection:
bigquery.connections.* - Set service account permissions:
resourcemanager.projects.getIamPolicyandresourcemanager.projects.setIamPolicy - Create a model and run inference:
bigquery.jobs.createbigquery.models.createbigquery.models.getDatabigquery.models.updateDatabigquery.models.updateMetadata
- Query table data:
bigquery.tables.getData
You might also be able to get these permissions withcustom roles or otherpredefined roles.
Before you begin
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
- Create a project: To create a project, you need the Project Creator role (
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission.Learn how to grant roles.
Verify that billing is enabled for your Google Cloud project.
Enable the BigQuery, BigQuery Connection, and Vertex AI APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission.Learn how to grant roles.
Create a dataset
Create a BigQuery dataset to contain your resources:
Console
In the Google Cloud console, go to theBigQuery page.
In the left pane, clickExplorer:

If you don't see the left pane, clickExpand left pane to open the pane.
In theExplorer pane, click your project name.
ClickView actions > Create dataset.
On theCreate dataset page, do the following:
ForDataset ID, type a name for the dataset.
ForLocation type, selectRegion orMulti-region.
- If you selectedRegion, then select a location from theRegion list.
- If you selectedMulti-region, then selectUS orEuropefrom theMulti-region list.
ClickCreate dataset.
bq
Create a connection
Create aCloud resource connectionand get the connection's service account. Create the connection inthe samelocation as the dataset you created in theprevious step.
You can skip this step if you either have a default connection configured, oryou have the BigQuery Admin role.
Select one of the following options:Console
Go to theBigQuery page.
In the left pane, clickExplorer:

If you don't see the left pane, clickExpand left pane to open the pane.
In theExplorer pane, expand your project name, and then clickConnections.
On theConnections page, clickCreate connection.
ForConnection type, chooseVertex AI remote models, remotefunctions, BigLake and Spanner (Cloud Resource).
In theConnection ID field, enter a name for your connection.
ForLocation type, select a location for your connection. Theconnection should be colocated with your other resources such asdatasets.
ClickCreate connection.
ClickGo to connection.
In theConnection info pane, copy the service account ID for use ina later step.
bq
In a command-line environment, create a connection:
bqmk--connection--location=REGION--project_id=PROJECT_ID\--connection_type=CLOUD_RESOURCECONNECTION_ID
The
--project_idparameter overrides the default project.Replace the following:
REGION: yourconnection regionPROJECT_ID: your Google Cloud project IDCONNECTION_ID: an ID for yourconnection
When you create a connection resource, BigQuery creates aunique system service account and associates it with the connection.
Troubleshooting: If you get the following connection error,update the Google Cloud SDK:
Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
Retrieve and copy the service account ID for use in a laterstep:
bqshow--connectionPROJECT_ID.REGION.CONNECTION_ID
The output is similar to the following:
name properties1234.REGION.CONNECTION_ID {"serviceAccountId": "connection-1234-9u56h9@gcp-sa-bigquery-condel.iam.gserviceaccount.com"}
Python
Before trying this sample, follow thePython setup instructions in theBigQuery quickstart using client libraries. For more information, see theBigQueryPython API reference documentation.
To authenticate to BigQuery, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.
importgoogle.api_core.exceptionsfromgoogle.cloudimportbigquery_connection_v1client=bigquery_connection_v1.ConnectionServiceClient()defcreate_connection(project_id:str,location:str,connection_id:str,):"""Creates a BigQuery connection to a Cloud Resource. Cloud Resource connection creates a service account which can then be granted access to other Google Cloud resources for federated queries. Args: project_id: The Google Cloud project ID. location: The location of the connection (for example, "us-central1"). connection_id: The ID of the connection to create. """parent=client.common_location_path(project_id,location)connection=bigquery_connection_v1.Connection(friendly_name="Example Connection",description="A sample connection for a Cloud Resource.",cloud_resource=bigquery_connection_v1.CloudResourceProperties(),)try:created_connection=client.create_connection(parent=parent,connection_id=connection_id,connection=connection)print(f"Successfully created connection:{created_connection.name}")print(f"Friendly name:{created_connection.friendly_name}")print(f"Service Account:{created_connection.cloud_resource.service_account_id}")exceptgoogle.api_core.exceptions.AlreadyExists:print(f"Connection with ID '{connection_id}' already exists.")print("Please use a different connection ID.")exceptExceptionase:print(f"An unexpected error occurred while creating the connection:{e}")Node.js
Before trying this sample, follow theNode.js setup instructions in theBigQuery quickstart using client libraries. For more information, see theBigQueryNode.js API reference documentation.
To authenticate to BigQuery, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.
const{ConnectionServiceClient}=require('@google-cloud/bigquery-connection').v1;const{status}=require('@grpc/grpc-js');constclient=newConnectionServiceClient();/** * Creates a new BigQuery connection to a Cloud Resource. * * A Cloud Resource connection creates a service account that can be granted access * to other Google Cloud resources. * * @param {string} projectId The Google Cloud project ID. for example, 'example-project-id' * @param {string} location The location of the project to create the connection in. for example, 'us-central1' * @param {string} connectionId The ID of the connection to create. for example, 'example-connection-id' */asyncfunctioncreateConnection(projectId,location,connectionId){constparent=client.locationPath(projectId,location);constconnection={friendlyName:'Example Connection',description:'A sample connection for a Cloud Resource',// The service account for this cloudResource will be created by the API.// Its ID will be available in the response.cloudResource:{},};constrequest={parent,connectionId,connection,};try{const[response]=awaitclient.createConnection(request);console.log(`Successfully created connection:${response.name}`);console.log(`Friendly name:${response.friendlyName}`);console.log(`Service Account:${response.cloudResource.serviceAccountId}`);}catch(err){if(err.code===status.ALREADY_EXISTS){console.log(`Connection '${connectionId}' already exists.`);}else{console.error(`Error creating connection:${err.message}`);}}}Terraform
Use thegoogle_bigquery_connectionresource.
To authenticate to BigQuery, set up Application DefaultCredentials. For more information, seeSet up authentication for client libraries.
The following example creates a Cloud resource connection namedmy_cloud_resource_connection in theUS region:
# This queries the provider for project information.data "google_project" "default" {}# This creates a cloud resource connection in the US region named my_cloud_resource_connection.# Note: The cloud resource nested object has only one output field - serviceAccountId.resource "google_bigquery_connection" "default" { connection_id = "my_cloud_resource_connection" project = data.google_project.default.project_id location = "US" cloud_resource {}}To apply your Terraform configuration in a Google Cloud project, complete the steps in the following sections.
Prepare Cloud Shell
- LaunchCloud Shell.
Set the default Google Cloud project where you want to apply your Terraform configurations.
You only need to run this command once per project, and you can run it in any directory.
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
Environment variables are overridden if you set explicit values in the Terraform configuration file.
Prepare the directory
Each Terraform configuration file must have its own directory (alsocalled aroot module).
- InCloud Shell, create a directory and a new file within that directory. The filename must have the
.tfextension—for examplemain.tf. In this tutorial, the file is referred to asmain.tf.mkdirDIRECTORY && cdDIRECTORY && touch main.tf
If you are following a tutorial, you can copy the sample code in each section or step.
Copy the sample code into the newly created
main.tf.Optionally, copy the code from GitHub. This is recommended when the Terraform snippet is part of an end-to-end solution.
- Review and modify the sample parameters to apply to your environment.
- Save your changes.
- Initialize Terraform. You only need to do this once per directory.
terraform init
Optionally, to use the latest Google provider version, include the
-upgradeoption:terraform init -upgrade
Apply the changes
- Review the configuration and verify that the resources that Terraform is going to create or update match your expectations:
terraform plan
Make corrections to the configuration as necessary.
- Apply the Terraform configuration by running the following command and entering
yesat the prompt:terraform apply
Wait until Terraform displays the "Apply complete!" message.
- Open your Google Cloud project to view the results. In the Google Cloud console, navigate to your resources in the UI to make sure that Terraform has created or updated them.
Grant a role to the remote model connection's service account
You must grant the connection's service account the Vertex AI User role.
If you plan to specify the endpoint as a URL when you create the remote model,for exampleendpoint = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/publishers/google/models/text-embedding-005',grant this role in the same project you specify in the URL.
If you plan to specify the endpoint by using the model name when you createthe remote model, for exampleendpoint = 'text-embedding-005', grant thisrole in the same project where you plan to create the remote model.
Granting the role in a different project results in the errorbqcx-1234567890-wxyz@gcp-sa-bigquery-condel.iam.gserviceaccount.com does not have the permission to access resource.
To grant the role, follow these steps:
Console
Go to theIAM & Admin page.
ClickGrant access.
TheAdd principals dialog opens.
In theNew principals field, enter the service account ID that youcopied earlier.
In theSelect a role field, selectVertex AI, and then selectVertex AI User.
ClickSave.
gcloud
Use thegcloud projects add-iam-policy-binding command:
gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/aiplatform.user' --condition=None
Replace the following:
PROJECT_NUMBER: your project numberMEMBER: the service account ID that you copied earlier
Choose an open model deployment method
If you are creating a remote model over asupported open model,you can automatically deploy the open model at the same time thatyou create the remote model by specifying the Vertex AIModel Garden or Hugging Face model ID in theCREATE MODEL statement.Alternatively, you can manually deploy the open model first, and then use thatopen model with the remote model by specifying the modelendpoint in theCREATE MODEL statement. For more information, seeDeploy open models.
Create a BigQuery ML remote model
Create a remote model:
New open models
Preview This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.
In the Google Cloud console, go to theBigQuery page.
Using the SQL editor, create aremote model:
CREATEORREPLACEMODEL`PROJECT_ID.DATASET_ID.MODEL_NAME`REMOTEWITHCONNECTION{DEFAULT|`PROJECT_ID.REGION.CONNECTION_ID`}OPTIONS({HUGGING_FACE_MODEL_ID='HUGGING_FACE_MODEL_ID'|MODEL_GARDEN_MODEL_NAME='MODEL_GARDEN_MODEL_NAME'}[,HUGGING_FACE_TOKEN='HUGGING_FACE_TOKEN'][,MACHINE_TYPE='MACHINE_TYPE'][,MIN_REPLICA_COUNT=MIN_REPLICA_COUNT][,MAX_REPLICA_COUNT=MAX_REPLICA_COUNT][,RESERVATION_AFFINITY_TYPE={'NO_RESERVATION'|'ANY_RESERVATION'|'SPECIFIC_RESERVATION'}][,RESERVATION_AFFINITY_KEY='compute.googleapis.com/reservation-name'][,RESERVATION_AFFINITY_VALUES=RESERVATION_AFFINITY_VALUES][,ENDPOINT_IDLE_TTL=ENDPOINT_IDLE_TTL]);
Replace the following:
PROJECT_ID: your project ID.DATASET_ID: the ID of the dataset to contain the model. This dataset must be in the samelocation as the connection that you are using.MODEL_NAME: the name of the model.REGION: the region used by the connection.CONNECTION_ID: the ID of your BigQuery connection.You can get this value byviewing 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 inConnection ID. For example,
projects/myproject/locations/connection_location/connections/myconnection.HUGGING_FACE_MODEL_ID: aSTRINGvalue that specifies the model ID for asupported Hugging Face model, in the formatprovider_name/model_name. For example,deepseek-ai/DeepSeek-R1. You can get the model ID by clicking the model name in the Hugging Face Model Hub and then copying the model ID from the top of the model card.MODEL_GARDEN_MODEL_NAME: aSTRINGvalue that specifies the model ID and model version of asupported Vertex AI Model Garden model, in the formatpublishers/publisher/models/model_name@model_version. For example,publishers/openai/models/gpt-oss@gpt-oss-120b. You can get the model ID by clicking the model card in the Vertex AI Model Garden and then copying the model ID from theModel ID field. You can get the default model version by copying it from theVersion field on the model card. To see other model versions that you can use, clickDeploy model and then click theResource ID field.HUGGING_FACE_TOKEN: aSTRINGvalue that specifies the Hugging FaceUser Access Token to use. You can only specify a value for this option if you also specify a value for theHUGGING_FACE_MODEL_IDoption.The token must have the
readrole at minimum but tokens with a broader scope are also acceptable. This option is required when the model identified by theHUGGING_FACE_MODEL_IDvalue is a Hugging Facegated or private model.Some gated models require explicit agreement to their terms of service before access is granted. To agree to these terms, follow these steps:
- Navigate to the model's page on the Hugging Face website.
- Locate and review the model's terms of service. A link to the service agreement is typically found on the model card.
- Accept the terms as prompted on the page.
MACHINE_TYPE: aSTRINGvalue that specifies the machine type to use when deploying the model to Vertex AI. For information about supported machine types, seeMachine types. If you don't specify a value for theMACHINE_TYPEoption, the Vertex AI Model Garden default machine type for the model is used.MIN_REPLICA_COUNT: anINT64value that specifies the minimum number of machine replicas used when deploying the model on a Vertex AI endpoint. The service increases or decreases the replica count as required by the inference load on the endpoint. The number of replicas used is never lower than theMIN_REPLICA_COUNTvalue and never higher than theMAX_REPLICA_COUNTvalue. TheMIN_REPLICA_COUNTvalue must be in the range[1, 4096]. The default value is1.MAX_REPLICA_COUNT: anINT64value that specifies the maximum number of machine replicas used when deploying the model on a Vertex AI endpoint. The service increases or decreases the replica count as required by the inference load on the endpoint. The number of replicas used is never lower than theMIN_REPLICA_COUNTvalue and never higher than theMAX_REPLICA_COUNTvalue. TheMAX_REPLICA_COUNTvalue must be in the range[1, 4096]. The default value is theMIN_REPLICA_COUNTvalue.RESERVATION_AFFINITY_TYPE: determines whether the deployed model usesCompute Engine reservations to provide assured virtual machine (VM) availability when serving predictions, and specifies whether the model uses VMs from all available reservations or just one specific reservation. For more information, seeCompute Engine reservation affinity.You can only use Compute Engine reservations that are shared with Vertex AI. For more information, seeAllow a reservation to be consumed.
Supported values are as follows:
NO_RESERVATION: no reservation is consumed when your model is deployed to a Vertex AI endpoint. SpecifyingNO_RESERVATIONhas the same effect as not specifying a reservation affinity.ANY_RESERVATION: the Vertex AI model deployment consumes virtual machines (VMs) from Compute Engine reservations that are in the current project or that areshared with the project, and that areconfigured for automatic consumption. Only VMs that meet the following qualifications are used:- They use the machine type specified by the
MACHINE_TYPEvalue. - If the BigQuery dataset in which you are creating the remote model is a single region, the reservation must be in the same region. If the dataset is in the
USmultiregion, the reservation must be in theus-central1region. If the dataset is in theEUmultiregion, the reservation must be in theeurope-west4region.
If there isn't enough capacity in the available reservations, or if no suitable reservations are found, the system provisions on-demand Compute Engine VMs to meet the resource requirements.
- They use the machine type specified by the
SPECIFIC_RESERVATION: the Vertex AI model deployment consumes VMs only from the reservation that you specify in theRESERVATION_AFFINITY_VALUESvalue. This reservation must beconfigured for specifically targeted consumption. Deployment fails if the specified reservation doesn't have sufficient capacity.
RESERVATION_AFFINITY_KEY: the stringcompute.googleapis.com/reservation-name. You must specify this option when theRESERVATION_AFFINITY_TYPEvalue isSPECIFIC_RESERVATION.RESERVATION_AFFINITY_VALUES: anARRAY<STRING>value that specifies the full resource name of the Compute Engine reservation, in the following format:projects/myproject/zones/reservation_zone/reservations/reservation_nameFor example,
RESERVATION_AFFINITY_values = ['projects/myProject/zones/us-central1-a/reservations/myReservationName'].You can get the reservation name and zone from theReservations page of the Google Cloud console. For more information, seeView reservations.
You must specify this option when the
RESERVATION_AFFINITY_TYPEvalue isSPECIFIC_RESERVATION.ENDPOINT_IDLE_TTL: anINTERVALvalue that specifies the duration of inactivity after which the open model is automatically undeployed from the Vertex AI endpoint.To enable automatic undeployment, specify aninterval literal value between 390 minutes (6.5 hours) and 7 days. For example, specify
INTERVAL 8 HOURto have the model undeployed after 8 hours of idleness. The default value is 390 minutes (6.5 hours).Model inactivity is defined as the amount of time that has passed since the any of the following operations were performed on the model:
- Running the
CREATE MODELstatement. - Running the
ALTER MODELstatement with theDEPLOY_MODELargument set toTRUE. - Sending an inference request to the model endpoint. For example, by running the
AI.GENERATE_EMBEDDINGorAI.GENERATE_TEXTfunction.
Each of these operations resets the inactivity timer to zero. The reset is triggered at the start of the BigQuery job that performs the operation.
After the model is undeployed, inference requests sent to the model return an error. The BigQuery model object remains unchanged, including model metadata. To use the model for inference again, you must redeploy it by running the
ALTER MODELstatement on the model and setting theDEPLOY_MODELoption toTRUE.- Running the
Deployed open models
In the Google Cloud console, go to theBigQuery page.
Using the SQL editor, create aremote model:
CREATEORREPLACEMODEL`PROJECT_ID.DATASET_ID.MODEL_NAME`REMOTEWITHCONNECTION{DEFAULT|`PROJECT_ID.REGION.CONNECTION_ID`}OPTIONS(ENDPOINT='https://ENDPOINT_REGION-aiplatform.googleapis.com/v1/projects/ENDPOINT_PROJECT_ID/locations/ENDPOINT_REGION/endpoints/ENDPOINT_ID');
Replace the following:
PROJECT_ID: your project ID.DATASET_ID: the ID of the dataset to contain the model. This dataset must be in the samelocation as the connection that you are using.MODEL_NAME: the name of the model.REGION: the region used by the connection.CONNECTION_ID: the ID of your BigQuery connection.You can get this value byviewing 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 inConnection ID. For example,
projects/myproject/locations/connection_location/connections/myconnection.ENDPOINT_REGION: the region in which the open model is deployed.ENDPOINT_PROJECT_ID: the project in which the open model is deployed.ENDPOINT_ID: the ID of the HTTPS endpoint used by the open model. You can get the endpoint ID by locating the open model on theOnline prediction page and copying the value in theID field.
All other models
In the Google Cloud console, go to theBigQuery page.
Using the SQL editor, create aremote model:
CREATEORREPLACEMODEL`PROJECT_ID.DATASET_ID.MODEL_NAME`REMOTEWITHCONNECTION{DEFAULT|`PROJECT_ID.REGION.CONNECTION_ID`}OPTIONS(ENDPOINT='ENDPOINT');
Replace the following:
PROJECT_ID: your project ID.DATASET_ID: the ID of the dataset to contain the model. This dataset must be in the samelocation as the connection that you are using.MODEL_NAME: the name of the model.REGION: the region used by the connection.CONNECTION_ID: the ID of your BigQuery connection.You can get this value byviewing 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 inConnection ID. For example,
projects/myproject/locations/connection_location/connections/myconnection.ENDPOINT: the name of an embedding model to use. For more information, seeENDPOINT.The Vertex AI model that you specify must be available in the location where you are creating the remote model. For more information, seeLocations.
Generate text embeddings
Generate text embeddings with theAI.GENERATE_EMBEDDING functionby using text data from a table column or a query.
Typically, you would use a text embedding model for text-only use cases, and amultimodal embedding model for cross-modal search use cases, where embeddingsfor text and visual content are generated in the same semantic space.
Vertex AI text
Generate text embeddings by using a remote model over aVertex AI text embedding model:
SELECT*FROMAI.GENERATE_EMBEDDING(MODEL`PROJECT_ID.DATASET_ID.MODEL_NAME`,{TABLEPROJECT_ID.DATASET_ID.TABLE_NAME|(CONTENT_QUERY)},STRUCT(TASK_TYPEAStask_type,OUTPUT_DIMENSIONALITYASoutput_dimensionality));
Replace the following:
PROJECT_ID: your project ID.DATASET_ID: the ID of the dataset that contains the model.MODEL_NAME: the name of the remote model over an embedding model.TABLE_NAME: the name of the table that contains the text to embed. This table must have a column that's namedcontent, or you can use an alias to use a differently named column.CONTENT_QUERY: a query whose result contains aSTRINGcolumn calledcontent.TASK_TYPE: aSTRINGliteral that specifies the intended downstream application to help the model produce better quality embeddings.TASK_TYPEaccepts the following values:RETRIEVAL_QUERY: specifies that the given text is a query in a search or retrieval setting.RETRIEVAL_DOCUMENT: specifies that the given text is a document in a search or retrieval setting.When using this task type, it is helpful to include the document title in the query statement in order to improve embedding quality. The document title must be in a column either named
titleor aliased astitle, for example:SELECT*FROMAI.GENERATE_EMBEDDING(MODEL
mydataset.embedding_model,(SELECTabstractascontent,headerastitle,publication_numberFROMmydataset.publications),STRUCT('RETRIEVAL_DOCUMENT'astask_type));Specifying the title column in the input query populates the
titlefield of the request body sent to the model. If you specify atitlevalue when using any other task type, that input is ignored and has no effect on the embedding results.SEMANTIC_SIMILARITY: specifies that the given text will be used for Semantic Textual Similarity (STS).CLASSIFICATION: specifies that the embeddings will be used for classification.CLUSTERING: specifies that the embeddings will be used for clustering.QUESTION_ANSWERING: specifies that the embeddings will be used for question answering.FACT_VERIFICATION: specifies that the embeddings will be used for fact verification.CODE_RETRIEVAL_QUERY: specifies that the embeddings will be used for code retrieval.
OUTPUT_DIMENSIONALITY: anINT64value that specifies the number of dimensions to use when generating embeddings. For example, if you specify256 AS output_dimensionality, then theembeddingoutput column contains a 256 dimensional embedding for each input value.For remote models over
gemini-embedding-001models, theOUTPUT_DIMENSIONALITYvalue must be in the range[1, 3072]. The default value is3072. For remote models overtext-embeddingmodels, theOUTPUT_DIMENSIONALITYvalue must be in the range[1, 768]. The default value is768.
Example: Embed text in a table
The following example shows a request to embed thecontent columnof thetext_data table:
SELECT*FROMAI.GENERATE_EMBEDDING(MODEL`mydataset.embedding_model`,TABLEmydataset.text_data,STRUCT('CLASSIFICATION'AStask_type));
Open text
Preview This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.
Generate text embeddings by using a remote model over an openembedding model:
SELECT*FROMAI.GENERATE_EMBEDDING(MODEL`PROJECT_ID.DATASET_ID.MODEL_NAME`,{TABLEPROJECT_ID.DATASET_ID.TABLE_NAME|(CONTENT_QUERY)},);
Replace the following:
PROJECT_ID: your project ID.DATASET_ID: the ID of the dataset that contains the model.MODEL_NAME: the name of the remote model over an embedding model.TABLE_NAME: the name of the table that contains the text to embed. This table must have a column that's namedcontent, or you can use an alias to use a differently named column.CONTENT_QUERY: a query whose result contains aSTRINGcolumn calledcontent.
Vertex AI multimodal
Generate text embeddings by using a remote model over aVertex AI multimodal embedding model:
SELECT*FROMAI.GENERATE_EMBEDDING(MODEL`PROJECT_ID.DATASET_ID.MODEL_NAME`,{TABLEPROJECT_ID.DATASET_ID.TABLE_NAME|(CONTENT_QUERY)},STRUCT(OUTPUT_DIMENSIONALITYASoutput_dimensionality));
Replace the following:
PROJECT_ID: your project ID.DATASET_ID: the ID of the dataset that contains the model.MODEL_NAME: the name of the remote model over amultimodalembedding@001model.TABLE_NAME: the name of the table that contains the text to embed. This table must have a column that's namedcontent, or you can use an alias to use a differently named column.CONTENT_QUERY: a query whose result contains aSTRINGcolumn calledcontent.OUTPUT_DIMENSIONALITY: anINT64value that specifies the number of dimensions to use when generating embeddings. Valid values are128,256,512, and1408. The default value is1408. For example, if you specify256 AS output_dimensionality, then theembeddingoutput column contains a 256-dimensional embedding for each input value.
Example: Use embeddings to rank semantic similarity
The following example embeds a collection of movie reviews and orders them bycosine distance to the review "This movie was average" using theVECTOR_SEARCH function.A smaller distance indicates more semantic similarity.
For more information about vector search and vector index, seeIntroduction to vector search.
CREATETEMPORARYTABLEmovie_review_embeddingsAS(SELECT*FROMAI.GENERATE_EMBEDDING(MODEL`bqml_tutorial.embedding_model`,(SELECT"This movie was fantastic"AScontentUNIONALLSELECT"This was the best movie I've ever seen!!"AScontentUNIONALLSELECT"This movie was just okay..."AScontentUNIONALLSELECT"This movie was terrible."AScontent)));WITHaverage_review_embeddingAS(SELECTembeddingFROMAI.GENERATE_EMBEDDING(MODEL`bqml_tutorial.embedding_model`,(SELECT"This movie was average"AScontent)))SELECTbase.contentAScontent,distanceASdistance_to_average_reviewFROMVECTOR_SEARCH(TABLEmovie_review_embeddings,"embedding",(SELECTembeddingFROMaverage_review_embedding),distance_type=>"COSINE",top_k=>-1)ORDERBYdistance_to_average_review;
The result is similar to the following:
+------------------------------------------+----------------------------+| content | distance_to_average_review |+------------------------------------------+----------------------------+| This movie was just okay... | 0.062789813467745592 || This movie was fantastic | 0.18579561313064263 || This movie was terrible. | 0.35707466240930985 || This was the best movie I've ever seen!! | 0.41844932504542975 |+------------------------------------------+----------------------------+
What's next
- Learn how touse text and image embeddings to perform a text-to-image semantic search.
- Learn how touse text embeddings for semantic search and retrieval-augmented generation (RAG).
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-02-19 UTC.