Use vector assist

This page describes how to use vector assist to deploy and manage a vector workload on your Cloud SQL for PostgreSQL instance.

To learn more about what vector assist is and how it works, see Vector assist overview.

Before you begin

  • Confirm your instance is using the correct maintenance version. vector assist requires a minimum maintenance version number of PostgreSQL_$version.R20251004.01_07. For more information about performing self-service maintenance, see Performance self-service maintenance.
  • Set the cloudsql.enable_vector_assist database flag to ON.

  • Enable the vector assist extension using the following command in the database you want to use:

    CREATE EXTENSION vector_assist CASCADE;

    This generates the vector_assist schema, which is used by vector assist.

Use vector assist to deploy a vector workload

To use vector assist to deploy and manage a vector workload, you must do the following:

Define your vector specification

Defining the vector specification, or vector spec is the first step in using vector assist. Depending on the type of vector workload, the fields you use to define your vector spec might be different.

For example, if you want to enable semantic search on a specific column in a table, run the vector_assist.define_spec function to define your vector spec:

SELECT vector_assist.define_spec(
  table_name => 'TABLE_NAME',
  vector_column_name => 'VECTOR_COLUMN_NAME',
  target_recall => TARGET_RECALL,
  tune_vector_index => TUNE_INDEX
);

Replace the following parameters:

  • TABLE_NAME: the name of the table you want to use in your vector workload.
  • VECTOR_COLUMN_NAME: the column you want to perform a semantic search on.
  • TARGET_RECALL: the target recall you want vector assist to meet.
  • TUNE_INDEX: a boolean that specifies whether vector assist tunes the vector indexes in your workload.

To see a complete list of all available parameters for the vector spec, see Vector assist reference.

After you run the query to create your vector spec, vector assist automatically generates steps, called recommendations, that you must run to deploy your vector workload.

View vector assist recommendations

To view the recommendations generated by vector assist using your vector spec, run the vector_assist.get_recommendations function:

SELECT vector_assist.get_recommendations(
  spec_id => 'SPEC_ID'
);

Replace the following parameters:

  • SPEC_ID: the spec ID of the vector spec that you want to view recommendations for.

Returns a table called vector_assist.RECOMMENDATIONS that contains all recommendations. Each recommendation is stored in a table with the associated spec_id. Each recommendation generally contains the SQL query you need to run, a detailed explanation for the recommendation, and other relevant information that explains the recommendation.

Apply vector assist recommendations

You can apply the generated recommendations individually or as a whole.

To apply a specific recommendation, run the vector_assist.apply_recommendation function:

SELECT vector_assist.apply_recommendation(
  recommendation_id => 'RECOMMENATION_ID',
);

Replace the following parameters:

  • RECOMMENDATION_ID: the ID of the vector assist recommendation you want to apply from the vector_assist.RECOMMENDATIONS table.

To apply all recommendations together, run the vector_assist.apply_spec function with either the spec_id or table_name parameter:

SELECT vector_assist.apply_spec(
  spec_id => 'SPEC_ID',
  table_name => 'TABLE_NAME'
);

Replace the following parameters:

  • SPEC_ID: the ID of the vector spec you want to use.
  • TABLE_NAME: the name of the table you used to define your vector spec.

Optionally, you can also input the schema_name or column_name parameters.

Once you apply the recommendations generated by vector assist, the vector index is ready for use.

Generate search queries

You can use vector assist to help you build optimized search queries for your deployed vector workloads using the workload's vector spec and generated vector index. To generate an optimized search query, run the vector_assist.generate_query function:

SELECT vector_assist.generate_query(
  spec_id => 'SPEC_ID',
  table_name => 'TABLE_NAME',
  column_name => 'COLUMN_NAME',
  search_text => 'SEARCH_TEXT',
  top_k => 'TOP_K_NAME',
  target_recall => TARGET_RECALL,
  filter_expression => 'FILTER_EXPRESSION'
);

Replace the following parameters:

  • SPEC_ID: the ID of the spec you want to use.
  • TABLE_NAME: the name of the table you used to define your vector spec.
  • COLUMN_NAME: the name of the original text column that you defined in your vector spec.
  • SEARCH_TEXT: the text that you want to search in the column.
  • TOP_K: the number of nearest neighbors to return.
  • TARGET_RECALL: the target recall you want vector assist to meet.
  • FILTER_EXPRESSION: any filters for the search query, for example, filtering based on other columns.

To see a complete list of all available parameters for generating a search query, see Vector assist reference.

The output of this function returns text that contains a SQL query. You can run or save this SQL query as necessary.

What's next