Run a vector similarity search

This document explains how to perform vector similarity searches in AlloyDB for PostgreSQL using the pgvector extension. Vector similarity search, also known as nearest neighbor search, lets you find the data points in your data that are most similar to a given query vector.

You can query your AlloyDB database for semantically similar vectors after storing and indexing embeddings. Use pgvector query features to find the nearest neighbors for an embedding vector.

For more information about storing vector embeddings and creating an index, see Store vector embeddings and Create indexes respectively.

To run a similarity search, specify the table, embedding column, distance function, target embedding, and the number of rows to return. You can also use the embedding() function to translate text into a vector and then compare the vector to stored embeddings using pgvector operators.

To find the nearest semantic neighbors for an embedding vector, you can run the following example query, where you set the same distance function that you used during the index creation.

  SELECT * FROM TABLE
    ORDER BY EMBEDDING_COLUMN DISTANCE_FUNCTION_QUERY ['EMBEDDING']
    LIMIT ROW_COUNT

Replace the following:

  • TABLE: the table containing the embedding to compare the text to.

  • EMBEDDING_COLUMN: the column containing the stored embeddings.

  • DISTANCE_FUNCTION_QUERY: the distance function to use with this query. Choose one of the following based on the distance function used while creating the index:

    • L2 distance: <->

    • Inner product: <#>

    • Cosine distance: <=>

  • EMBEDDING: the embedding vector you want to find the nearest stored semantic neighbors of.

  • ROW_COUNT: the number of rows to return.

    Specify 1 if you want only the single best match.

For more information about other query examples, see Querying.

You can use also use the embedding() function to translate the text into a vector, and to find the database rows with the most semantically similar embeddings. The stock pgvector PostgreSQL extension is customized for AlloyDB, and referred to as vector. You apply the vector to one of the pgvector nearest-neighbor operators, for example <=> for cosine distance.

Because embedding() returns a real array, you must explicitly cast the embedding() call to vector in order to use these values with pgvector operators.

  CREATE EXTENSION IF NOT EXISTS vector;

  SELECT * FROM TABLE
    ORDER BY EMBEDDING_COLUMN::vector
    <=> google_ml.embedding('MODEL_IDVERSION_TAG', 'TEXT')
    LIMIT ROW_COUNT

Replace the following:

  • MODEL_ID: the ID of the model to query.

    If you are using the Vertex AI Model Garden, then specify text-embedding-005 as the model ID. These are the cloud-based models that AlloyDB can use for text embeddings. For more information, see Text embeddings.

  • Optional: VERSION_TAG: the version tag of the model to query. Prepend the tag with @.

    If you are using one of the text-embedding-005 English models with Vertex AI, then specify one of the version tags—for example, text-embedding-005, listed in Model versions.

    Google strongly recommends that you always specify the version tag. If you don't specify the version tag, then AlloyDB uses the latest model version, which might lead to unexpected results.

  • TEXT: the text to translate into a vector embedding.

To accelerate your filtered KNN search, you can use the AlloyDB columnar engine. For more information, see Accelerate your filtered vector search (Preview) and Configure the columnar engine.

What's next