The AI.EMBED function

Text embedding

AI.EMBED(
  [ content => ] 'content',
  { endpoint => 'endpoint' | model => 'model' }
  [, task_type => 'task_type']
  [, title => 'title']
  [, model_params => model_params]
  [, connection_id => 'connection']
)

Arguments

AI.EMBED takes the following arguments:

• content: a STRING value that provides the text to embed.

  The content value can be a string literal, the name of a table column, or the output of an expression that evaluates to a string.

• endpoint: a STRING value that specifies a supported Gemini Enterprise Agent Platform text embedding model endpoint to use for the text embedding model. The function incurs charges in Agent Platform each time it's called.

  The endpoint value that you specify must include the model version, for example, text-embedding-005. If you specify the model name rather than a URL, BigQuery ML automatically identifies the model and uses the model's full endpoint. For more information, see Choose a model.

• model (Preview): a STRING value that specifies a built-in text embedding model. The only supported value is the embeddinggemma-300m model. For more information, see Choose a model.

  If you specify this parameter, you can't specify the endpoint, title, model_params, or connection_id parameters. Your data stays in BigQuery and your slots are used to create the embeddings; no data is sent to Agent Platform and no charges are incurred in Agent Platform.

  To request feedback or support for this feature, send email to bqml-feedback@google.com.

• task_type: a STRING literal that specifies the intended downstream application to help the model produce better quality embeddings. The task_type argument accepts 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.
  • 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.
  Not compatible with the gemini-embedding-2-preview model endpoint.
• title: A STRING value that specifies the document title, which the model uses to improve embedding quality. You can only use this parameter if you specify RETRIEVAL_DOCUMENT for the task_type value. Not compatible with the gemini-embedding-2-preview model endpoint.
• model_params: a JSON literal that provides additional parameters to the model. You can use any of the parameters object fields. One of these fields, outputDimensionality, lets you specify the number of dimensions to use when generating embeddings. For example, if you specify 256 for the outputDimensionality field, then the model returns a 256-dimensional embedding for each input value.
• 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.

  For user-initiated queries, the CONNECTION argument is optional. When a user initiates a query, BigQuery ML uses the credentials of the user who submitted the query to run it.

  If your query job is expected to run for 48 hours or longer, you should use the CONNECTION argument to run the query using a service account.

  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 region in which the query is run.
  • CONNECTION_ID: the connection IDfor 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 Agent Platform User role to the connection's service account in the project where you run the function.

Multimodal embedding

AI.EMBED(
  [ content => ] 'content',
  endpoint => 'endpoint'
  [, connection_id => 'connection']
  [, model_params => model_params]
)

Arguments

AI.EMBED takes the following arguments:

• content: a STRING or ObjectRef value that provides the data to embed.
  • For text embeddings, you can specify one of the following:
    • A string literal.
    • The name of a STRING column.
    • The output of an expression that evaluates to a string.
  • For image content embeddings, you can specify one of the following:
    • The name of an ObjectRef column.
    • An ObjectRef value.
  • If you use the gemini-embedding-2-preview model (Preview), you can also specify a STRUCT that contains a combination of STRING, ARRAY<STRING>, ObjectRef, and ARRAY<ObjectRef> values.

  ObjectRef values must have the details.gcs_metadata.content_type elements of the JSON value populated.

• 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 region in which the query is run.
  • CONNECTION_ID: the connection IDfor 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 Agent Platform User role to the connection's service account in the project where you run the function.

• endpoint: a STRING value that specifies a supported Agent Platform multimodal embedding model endpoint to use for the multimodal embedding model. The endpoint value that you specify must include the model version, for example gemini-embedding-2-preview. If you specify the model name rather than a URL, BigQuery ML automatically identifies the model and uses the model's full endpoint.
• model_params: a JSON literal that provides additional parameters to the model. Only the dimension field is supported. You can use the dimension field to specify the number of dimensions to use when generating embeddings. For example, if you specify 256 for the dimension field, then the model returns a 256-dimensional embedding for each input value. For more information, see how to specify lower-dimensional embeddings.

text embedding

The following example shows how to embed a string literal using an Agent Platform endpoint:

SELECT
  AI.EMBED(
    'A piece of text to embed',
    endpoint => 'text-embedding-005') AS embedding;

The result is similar to the following:

+-----------------------+------------------+
| embedding.result      | embedding.status |
+-----------------------+------------------+
| 0.11416172981262207   |                  |
| 0.0041960999369621277 |                  |
| ...                   |                  |
+-----------------------+------------------+

The embedding.result column contains a single row with an array of length 768. The embedding.status column contains an empty string, which indicates that the embedding was successful.

Alternatively, you can perform the embedding by using a built-in embedding model in BigQuery:

SELECT
  AI.EMBED(
    'A piece of text to embed',
    model => 'embeddinggemma-300m') AS embedding;

If you need to reuse embeddings of the same data across many queries, you should save the results to table. The following example generates 768-dimensional embeddings for publicly available BBC news articles and writes the results to a table:

CREATE OR REPLACE TABLE mydataset.bbc_news_embeddings AS
SELECT
  title,
  body,
  AI.EMBED(
    body,
    endpoint => 'text-embedding-005',
    model_params => JSON '{"outputDimensionality": 768}'
  ).result AS embedding
FROM
  `bigquery-public-data.bbc_news.fulltext`;

The following example queries the table that you just created for the five articles that are most related to the topic "latest news in tech". It calls the VECTOR_SEARCH function and uses AI.EMBED to create an embedding to pass to the function as the search query.

SELECT base.title, base.body
FROM
  VECTOR_SEARCH(
    TABLE mydataset.bbc_news_embeddings,
    # The name of the column that contains the embedding
    'embedding',
    # The embedding to search
    (SELECT AI.EMBED('latest news in tech', endpoint => 'text-embedding-005').result),
    top_k => 5);

multimodal embedding

The following query creates an external table from images of pet products stored in a publicly available Cloud Storage bucket. Then, it generates embeddings for two of the images:

# Create a dataset
CREATE SCHEMA IF NOT EXISTS cymbal_pets;

# Create an object table
CREATE OR REPLACE EXTERNAL TABLE cymbal_pets.product_images
WITH CONNECTION DEFAULT
OPTIONS (
  object_metadata = 'SIMPLE',
  uris = ['gs://cloud-samples-data/bigquery/tutorials/cymbal-pets/images/*.png']
);

SELECT
  ref.uri,
  OBJ.GET_READ_URL(ref).url AS signed_url,
  AI.EMBED(
    ref,
    endpoint => 'multimodalembedding@001') AS embedding
FROM
  `cymbal_pets.product_images`
LIMIT 2;

The following query uses the gemini-embedding-2-preview (Preview) model to embed the combination of a text description and an image:

SELECT
  AI.EMBED(
    ('Made of tempered glass',
    OBJ.MAKE_REF('gs://cloud-samples-data/bigquery/tutorials/cymbal-pets/images/aquaclear-20-gallon-aquarium.png')),
    endpoint => 'gemini-embedding-2-preview');