Get Vertex AI text embeddings

This page describes how to use theVertex AI text embeddingAPI to generate, store, and update text embeddings for data stored inSpanner for GoogleSQL-dialect databases and PostgreSQL-dialect databases.

A text embedding is a vector representation of text data, and they are used inmany ways to find similar items. You interact with them every time you completea Google Search or see recommendations when shopping online.When you create text embeddings, you get vector representations of natural textas arrays of floating point numbers. This means that all of your inputtext is assigned a numerical representation. By comparing the numerical distancebetween the vector representations of two pieces of text, an application candetermine the similarity between the text or the objects represented by thetext.

With the Vertex AI text embeddings API, you can create atext embedding withGenerative AI. Inthis tutorial, you use the Vertex AI text embedding model togenerate text embeddings for the data stored in Spanner.

To learn more about text embeddings and supported models, seeGet text embeddings.

Objective

In this tutorial, you learn how to:

  • Register aVertex AI text embedding modelin a Spanner schema using DDL statements.
  • Reference the registered model using SQL queries to generate embeddings fromdata stored in Spanner.

Pricing

This tutorial uses billable components of Google Cloud, including:

  • Spanner
  • Vertex AI

For more information about Spanner costs, see theSpanner pricing page.

For more information about Vertex AI costs, see theVertex AI pricing page.

Generate and store text embeddings

Depending on the model you use, generating embeddings might take some time. Formore performance sensitive workloads, the best practice is to avoid generatingembeddings in read-write transactions. Instead, generate the embeddings in aread-only transaction using the following SQL examples.

GoogleSQL

Register a text embeddings model in Spanner

In GoogleSQL, you must register a model before using it withtheML.PREDICT function. To register the Vertex AI textembedding model in a Spanner database,execute the following DDLstatement:

CREATEMODELMODEL_NAMEINPUT(contentSTRING(MAX),-- Optional: For models that support specifying task type.task_typeSTRING(MAX),)OUTPUT(embeddingsSTRUCT<statisticsSTRUCT<truncatedBOOL,token_countFLOAT64>,valuesARRAY<FLOAT64>>)REMOTEOPTIONS(endpoint='//aiplatform.googleapis.com/projects/PROJECT/locations/LOCATION/publishers/google/models/$MODEL_NAME');

Replace the following:

  • MODEL_NAME: the name of the Vertex AI text embedding model
  • PROJECT: the project hosting the Vertex AI endpoint
  • LOCATION: the location of the Vertex AI endpoint

Spanner grants appropriate permissions automatically. If itdoesn't, review themodel endpoint access control.

Schema discovery and validation is not available for Generative AImodels. You are required to provideINPUT andOUTPUT clauses which matchagainst the models schema. For the full schema of the text embedding model,seeGet text embeddings.

Generate text embeddings

To generate embeddings, pass a piece of text directly to theML.PREDICT function using the following SQL:

SELECTembeddings.valuesFROMML.PREDICT(MODELMODEL_NAME,(SELECT"A product description"ascontent));

To generate embeddings for data stored in a table, use the following SQL:

SELECTid,embeddings.valuesFROMML.PREDICT(MODELMODEL_NAME,(SELECTid,descriptionascontentFROMProducts));

To specifytask type andoutput dimensions:

UPDATEProductspSETdescription_embedding=(SELECTembeddings.valuesFROMML.PREDICT(MODELMODEL_NAME,(SELECTp.descriptionascontent,"RETRIEVAL_DOCUMENT"astask_type),STRUCT(768ASoutputDimensionality)));SELECTp.product_id,p.name,p.description,COSINE_DISTANCE(p.description_embedding,(SELECTembeddings.valuesFROMML.PREDICT(MODELMODEL_NAME,(SELECT@user_queryascontent,"RETRIEVAL_QUERY"astask_type),STRUCT(768ASoutputDimensionality))))ASdistanceFROMProductspORDERBYdistanceLIMIT5;

Store text embeddings

After generating the embeddings in a read-only transaction, store them inSpanner so they can be managed with your operational data. Tostore the embeddings, use aread-write transaction.

For workloads that are less performance sensitive, you can generate and insertembeddings with the following SQL in a read-write transaction:

CREATETABLEProducts(idINT64NOTNULL,descriptionSTRING(MAX),embeddingsARRAY<FLOAT32>,)PRIMARYKEY(id);
INSERTINTOProducts(id,description,embeddings)SELECT@Id,@Description,embeddings.valuesFROMML.PREDICT(MODELMODEL_NAME,(SELECT@Descriptionascontent));

PostgreSQL

Generate text embeddings

To generate embeddings, pass a piece of text directly to thespanner.ML_PREDICT_ROW function using the following SQL:

SELECTspanner.ML_PREDICT_ROW('projects/PROJECT/locations/LOCATION/publishers/google/models/$MODEL_NAME','{"instances": [{"content": "A product description"}]}'::jsonb)->'predictions'->0->'embeddings'->'values';

Replace the following:

  • PROJECT: the project hosting the Vertex AI endpoint
  • LOCATION: the location of the Vertex AI endpoint
  • MODEL_NAME: the name of the Vertex AI text embedding model

To generate embeddings for data stored in a table, use the following SQL:

SELECTid,spanner.ML_PREDICT_ROW('projects/PROJECT/locations/LOCATION/publishers/google/models/$MODEL_NAME',JSONB_BUILD_OBJECT('instances',JSONB_BUILD_ARRAY(JSONB_BUILD_OBJECT('content',description)))))->'predictions'->0->'embeddings'->'values'FROMProducts;

Replace the following:

  • PROJECT: the project hosting the Vertex AI endpoint
  • LOCATION: the location of the Vertex AI endpoint
  • MODEL_NAME: the name of the Vertex AI text embedding model

To specifytask type andoutput dimensions:

UPDATEProductspSETdescription_embedding=spanner.float64_array(spanner.ML_PREDICT_ROW('projects/PROJECT/locations/LOCATION/publishers/google/models/$MODEL_NAME',JSONB_BUILD_OBJECT('instances',JSONB_BUILD_ARRAY(JSONB_BUILD_OBJECT('content',p.description,'task_type','RETRIEVAL_DOCUMENT')),'parameters',JSONB_BUILD_OBJECT('outputDimensionality',768)))->'predictions'->0->'embeddings'->'values');SELECTp.product_id,p.name,p.description,spanner.COSINE_DISTANCE(p.description_embedding,spanner.float64_array(spanner.ML_PREDICT_ROW('projects/PROJECT/locations/LOCATION/publishers/google/models/$MODEL_NAME',JSONB_BUILD_OBJECT('instances',JSONB_BUILD_ARRAY(JSONB_BUILD_OBJECT('content',$1,'task_type','RETRIEVAL_QUERY')),'parameters',JSONB_BUILD_OBJECT('outputDimensionality',768)))->'predictions'->0->'embeddings'->'values'))ASdistanceFROMProductspORDERBYdistanceLIMIT5;

Replace the following:

  • PROJECT: the project hosting the Vertex AI endpoint
  • LOCATION: the location of the Vertex AI endpoint
  • MODEL_NAME: the name of the Vertex AI text embedding model

Store text embeddings

After generating the embeddings in a read-only transaction, store them inSpanner so they can be managed with your operational data. Tostore the embeddings, use aread-write transaction.

For workloads that are less performance sensitive, you can generate and insertembeddings with the following SQL in a read-write transaction:

CREATETABLEProducts(idINT8NOTNULL,descriptionTEXT,embeddingsREAL[],PRIMARYKEY(id));
INSERTINTOProducts(id,description,embeddings)SELECT@Id,@Description,spanner.FLOAT32_ARRAY(spanner.ML_PREDICT_ROW('projects/PROJECT/locations/LOCATION/publishers/google/models/$MODEL_NAME',JSONB_BUILD_OBJECT('instances',JSONB_BUILD_ARRAY(JSONB_BUILD_OBJECT('content',@Description))))->'predictions'->0->'embeddings'->'values'));

Replace the following:

  • PROJECT: the project hosting the Vertex AI endpoint
  • LOCATION: the location of the Vertex AI endpoint
  • MODEL_NAME: the name of the Vertex AI text embedding model

Update text embeddings

To update your embeddings or to ingest data in realtime, use theUPDATE(GoogleSQLandPostgreSQL)statement.

To update theProducts table in the previous example, use the following SQL:

GoogleSQL

UPDATEProductsSETdescription=@description,embeddings=(SELECTembeddings.valuesFROMML.PREDICT(MODELMODEL_NAME,(SELECT@descriptionascontent)))WHEREid=@id;

Replace the following:

  • MODEL_NAME: the name of the Vertex AI text embedding model

PostgreSQL

UPDATEProductsSETdescription=$1,embeddings=spanner.FLOAT32_ARRAY(spanner.ML_PREDICT_ROW('projects/PROJECT/locations/LOCATION/publishers/google/models/$MODEL_NAME',JSONB_BUILD_OBJECT('instances',JSONB_BUILD_ARRAY(JSONB_BUILD_OBJECT('content',$1))))->'predictions'->0->'embeddings'->'values')WHEREid=$2;

Replace the following:

  • PROJECT: the project hosting the Vertex AI endpoint
  • LOCATION: the location of the Vertex AI endpoint
  • MODEL_NAME: the name of the Vertex AI text embedding model

What's next

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.