> [!WARNING] > > **Preview > --- Vector assist** > > > This feature is > > subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the > [Service Specific > Terms](https://docs.cloud.google.com/terms/service-terms#1). > > You can process personal data for > > this feature > > as outlined in the > [Cloud Data > Processing Addendum](https://docs.cloud.google.com/terms/data-processing-addendum), subject to the obligations and restrictions described in the > agreement under which you access Google Cloud. > > Pre-GA features are available "as is" and might have limited support. > > For more information, see the > [launch stage descriptions](https://cloud.google.com/products/#product-launch-stages). > [!WARNING] > **Warning:** Vector assist ([Preview](https://cloud.google.com/products)) is temporarily disabled for all Cloud SQL for PostgreSQL instances. 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](https://docs.cloud.google.com/sql/docs/postgres/vector-assist-overview.md.txt). ## 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](https://docs.cloud.google.com/sql/docs/postgres/self-service-maintenance.md.txt). - [Set the `cloudsql.enable_vector_assist` database flag to `ON`](https://docs.cloud.google.com/sql/docs/postgres/flags.md.txt#set_a_database_flag). - Enable the vector assist extension using the following command in the database you want to use: ```sql 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](https://docs.cloud.google.com/sql/docs/postgres/use-vector-assist.md.txt#define-spec) - [View vector assist recommendations](https://docs.cloud.google.com/sql/docs/postgres/use-vector-assist.md.txt#view-recommendations) - [Apply vector assist recommendations](https://docs.cloud.google.com/sql/docs/postgres/use-vector-assist.md.txt#apply-recommendations) ### Define your vector specification Defining the [vector specification](https://docs.cloud.google.com/sql/docs/postgres/vector-assist-overview.md.txt#vector-spec), 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`](https://docs.cloud.google.com/sql/docs/postgres/vector-assist-reference.md.txt#define-spec) function to define your vector spec: ```sql 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](https://docs.cloud.google.com/sql/docs/postgres/vector-assist-reference.md.txt). 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`](https://docs.cloud.google.com/sql/docs/postgres/vector-assist-reference.md.txt#get-recommendations) function: ```sql 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`](https://docs.cloud.google.com/sql/docs/postgres/vector-assist-reference.md.txt#apply-recommendation) function: ```sql 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`](https://docs.cloud.google.com/sql/docs/postgres/vector-assist-reference.md.txt#apply-spec) function with either the `spec_id` or `table_name` parameter: ```sql 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`](https://docs.cloud.google.com/sql/docs/postgres/vector-assist-reference.md.txt#generate-query) function: ```sql 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](https://docs.cloud.google.com/sql/docs/postgres/vector-assist-reference.md.txt). 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 - Learn more about [vector assist](https://docs.cloud.google.com/sql/docs/postgres/vector-assist-overview.md.txt). - [Vector assist reference](https://docs.cloud.google.com/sql/docs/postgres/vector-assist-reference.md.txt).