# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

Text + multimodal embedding generation and vector search in BigQuery with BigFrames#

Colab logo Run in Colab GitHub logo View on GitHub Colab Enterprise logo Open in Colab Enterprise BQ logo Open in BQ Studio

Share to:

LinkedIn logo Bluesky logo X logo Reddit logo Facebook logo

Overview#

Objectives#

In this tutorial, you’ll build a semantic search utility for a fictional e-commerce pet store using BigQuery, BigQuery DataFrames (BigFrames), and Gemini Enterprise Agent Platform. Unlike simple keyword matching, semantic search uses vector embeddings to capture the conceptual meaning of both product descriptions and product images. This enables customers to find products based on intent and visual attributes, creating a much more intuitive shopping experience.

By the end of this tutorial, you will know how to:

  • Load data directly from Google Cloud Storage into a BigFrames DataFrame using bpd.read_parquet.

  • Generate text embeddings on DataFrame columns using bigframes.bigquery.ai.embed.

  • Perform text-to-text vector search with bigframes.bigquery.vector_search to find products with semantically similar descriptions.

  • Work with unstructured image data using BigFrames’ ObjectRef functions (bbq.obj.make_ref, bbq.obj.fetch_metadata, bbq.obj.get_access_url) and generate multimodal embeddings.

  • Perform text-to-image vector search to find product images that visually match a natural language text query.

All seamlessly orchestrated using Python and BigFrames!

Services and Costs#

This tutorial uses the following billable components of Google Cloud:

  • BigQuery: Pricing

  • Gemini Enterprise Agent Platform (Embeddings API): Pricing

You can use the Pricing Calculator to generate a cost estimate based on your projected usage.


Before you begin#

Set up your Google Cloud project#

The following steps are required, regardless of your notebook environment.

  1. Select or create a Google Cloud project. When you first create an account, you get a $300 free credit towards your compute/storage costs.

  2. Make sure that billing is enabled for your project.

  3. Enable the BigQuery, BigQuery Connection, and Agent Platform APIs.

  4. If you are running this notebook locally, you need to install the Cloud SDK.

Set your project ID#

PROJECT_ID = ""  # @param {type:"string"}

# Set the project id
! gcloud config set project {PROJECT_ID}

Authenticate to your Google Cloud account#

Depending on your Jupyter environment, you may have to manually authenticate. Follow the relevant instructions below.

1. Colab Enterprise or BigQuery Studio Notebooks

  • Do nothing as you are already authenticated.

2. Colab, uncomment and run:

# from google.colab import auth

# auth.authenticate_user()

3. Local JupyterLab instance, uncomment and run:

# ! gcloud auth login

Create helper function to render images from Google Cloud Storage in this notebook#

This is a helpful utility function that you’ll use later in the tutorial. It takes the results of your search query (stored in a DataFrame) and displays the corresponding product images in a nice grid format, making it easy to see how well your search worked.

Import necessary libraries for BigFrames and the helper function#

# Imports for BigFrames, BigQuery, GCS, plotting, and image handling
import io
import math

import bigframes.bigquery as bbq
import bigframes.pandas as bpd
from google.cloud import bigquery
from google.cloud import storage
import matplotlib.pyplot as plt
from PIL import Image

Configure BigFrames and create a Google Cloud Storage client#

# Set variables
REGION = "US"
bucket = "sample-data-and-media"

# Configure BigFrames and create clients
bpd.options.bigquery.project = PROJECT_ID
bpd.options.bigquery.location = REGION
bq_client = bigquery.Client(project=PROJECT_ID)
client = storage.Client(project=PROJECT_ID)
bucket = client.bucket(bucket)
def display_product_images(df):
  """Displays product images from a DataFrame in a 3-column grid.

  Simplified for clarity in a tutorial context.
  """
  # Calculate grid size
  num_images = len(df)
  cols = 3
  rows = math.ceil(num_images / cols)

  fig, axs = plt.subplots(rows, cols, figsize=(10, rows * 3.5))

  # Flatten the axes array for easy iteration, regardless of shape
  axs = axs.flatten()

  for i, row in df.reset_index(drop=True).iterrows():
    # Extract the image path from the full GCS URI
    image_path = row["uri"].split("/", 3)[-1]

    # Get the image from GCS
    blob = bucket.blob(image_path)
    image = Image.open(io.BytesIO(blob.download_as_bytes()))

    # Plot the image
    axs[i].imshow(image)
    axs[i].set_title(image_path.split("/")[-1], fontsize=10)
    axs[i].axis("off")

  # Hide any unused subplots
  for j in range(num_images, len(axs)):
    axs[j].axis("off")

  plt.tight_layout()
  plt.show()

Load and prepare the sample data#

Load the products DataFrame directly from Cloud Storage#

BigQuery DataFrames allows you to load data directly from Google Cloud Storage into a DataFrame without needing to manually create a BigQuery dataset or persistent table first.

This code uses bigframes.pandas.read_parquet with engine="bigquery" to read the pet products catalog from a public Parquet file in Google Cloud Storage (gs://sample-data-and-media/cymbal-pets/tables/products). BigQuery processes and executes transformations on this data directly in the cloud while providing a familiar pandas-like DataFrame API.

Read the data into a BigFrames DataFrame and inspect the first two rows to confirm the product catalog schema and contents:

products = bpd.read_parquet(
    "gs://sample-data-and-media/cymbal-pets/tables/products",
    engine="bigquery",
)
products.head(2)



Clean up#

Because this tutorial executed all transformations and vector searches directly within BigFrames using ephemeral query jobs, without creating persistent BigQuery datasets, tables, or custom models, there are no permanent BigQuery datasets or models to delete.

To release any temporary BigQuery tables and session resources allocated during this notebook run, you can close the active BigFrames session using bpd.close_session() in the below code cell.

If you created a dedicated Google Cloud project specifically for this tutorial and no longer need it, you can also delete the project to prevent any future charges.

bpd.close_session()