cloud-sql-postgres-vectorassist

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Usage

使用方法

All scripts can be executed using Node.js. Replace

<param_name>

and

<param_value>

with actual values.

Bash:

node <skill_dir>/scripts/<script_name>.js '{"<param_name>": "<param_value>"}'

PowerShell:

node <skill_dir>/scripts/<script_name>.js '{\"<param_name>\": \"<param_value>\"}'

Note: The scripts automatically load the environment variables from various .env files. Do not ask the user to set vars unless skill executions fails due to env var absence.

所有脚本均可通过Node.js执行。将

<param_name>

和

<param_value>

替换为实际值。

Bash：

node <skill_dir>/scripts/<script_name>.js '{"<param_name>": "<param_value>"}'

PowerShell：

node <skill_dir>/scripts/<script_name>.js '{\"<param_name>\": \"<param_value>\"}'

注意：脚本会自动从多个.env文件加载环境变量。除非因缺少环境变量导致技能执行失败，否则无需要求用户设置变量。

Scripts

脚本

apply_spec

This tool automatically executes all the SQL recommendations associated with a specific vector specification (spec_id) or table. It runs the necessary commands in the correct sequence to provision the workload, marking each step as applied once successful. Use this tool when the user has reviewed the generated recommendations from a defined (or modified) spec and is ready to apply the changes directly to their database instance to finalize the vector search setup. This tool can be used as a follow-up action after invoking the 'define_spec' or 'modify_spec' tool.

该工具会自动执行与特定向量规格（spec_id）或表相关的所有SQL建议。它会按正确顺序运行必要的命令来部署工作负载，成功完成每个步骤后会标记为已应用。当用户已查看从已定义（或修改）的规格生成的建议，并准备直接将更改应用到数据库实例以完成向量搜索设置时，可使用此工具。此工具可作为调用

define_spec

或

modify_spec

工具后的后续操作。

Parameters

参数

Name	Type	Description	Required
spec_id	string	The unique ID of the vector specification to apply.	No
table_name	string	The name of the table to apply the vector specification to (in case of a single spec defined on the table).	No
column_name	string	The text_column_name or vector_column_name of the spec to identify the exact spec in case there are multiple specs defined on a table.	No
schema_name	string	The schema name for the table.	No

名称	类型	描述	必填
spec_id	string	要应用的向量规格的唯一ID。	否
table_name	string	要应用向量规格的表名（适用于表上仅定义了单个规格的情况）。	否
column_name	string	当表上定义了多个规格时，用于标识具体规格的text_column_name或vector_column_name。	否
schema_name	string	表所属的模式名。	否

define_spec

This tool defines a new vector specification by capturing the user's intent and requirements for a vector search workload. This generates a complete, ordered set of SQL recommendations required to set up the database, embeddings, and vector indexes. While highly customizable, any optional parameters left unspecified will use internally determined defaults optimized for the specific workload. Use this tool at the very beginning of the vector setup process when a user first wants to configure a table for vector search, generate embeddings, or create a new vector index.

该工具通过捕捉用户对向量搜索工作负载的需求和要求，定义新的向量规格。它会生成一套完整、有序的SQL建议，用于设置数据库、嵌入模型和向量索引。虽然高度可自定义，但任何未指定的可选参数都将使用针对特定工作负载优化的内部默认值。当用户首次想要为表配置向量搜索、生成嵌入向量或创建新的向量索引时，可在向量设置流程的最开始使用此工具。

Parameters

参数

Name	Type	Description	Required
table_name	string	Table name on which vector workload needs to be set up.	Yes
schema_name	string	Schema containing the given table.	No
spec_id	string	Unique ID for the vector spec. Auto-generated, if not specified.	No
vector_column_name	string	Column name for the column with vector embeddings.	No
text_column_name	string	Column name for the column with text on which vector search needs to be set up.	No
vector_index_type	string	Type of the vector index to be created (Allowed inputs: 'hnsw', 'ivfflat', 'scann').	No
embeddings_available	boolean	Boolean parameter to know if vector embeddings are already available in the table.	No
num_vectors	integer	Number of vectors expected in the dataset.	No
dimensionality	integer	If vectors are already generated, set to dimension of vectors. If not, set to dimensionality of the embedding_model.	No
embedding_model	string	Optional parameter: Model to be used for generating embeddings. If not provided, it has an internally selected default value.	No
prefilter_column_names	array	Columns based on which prefiltering will happen in vector search queries.	No
distance_func	string	Distance function to be used for comparing vectors (Allowed inputs: 'cosine', 'ip', 'l2', 'l1').	No
quantization	string	Quantization to be used for creating the vector indexes (Allowed inputs: 'none', 'halfvec', 'bit').	No
memory_budget_kb	integer	Maximum size in KB that the index can consume in memory while building.	No
target_recall	float	The recall that the user would like to target with the given index for standard vector queries.	No
target_top_k	integer	The top-K values that need to be retrieved for the given query.	No
tune_vector_index	boolean	Boolean parameter to specify if the auto tuning is required for the index.	No

名称	类型	描述	必填
table_name	string	需要设置向量工作负载的表名。	是
schema_name	string	包含该表的模式。	否
spec_id	string	向量规格的唯一ID。若未指定，将自动生成。	否
vector_column_name	string	存储向量嵌入的列名。	否
text_column_name	string	需要设置向量搜索的文本列名。	否
vector_index_type	string	要创建的向量索引类型（允许输入：'hnsw'、'ivfflat'、'scann'）。	否
embeddings_available	boolean	用于判断表中是否已存在向量嵌入的布尔参数。	否
num_vectors	integer	数据集中预期的向量数量。	否
dimensionality	integer	若向量已生成，设置为向量的维度；若未生成，设置为embedding_model的维度。	否
embedding_model	string	可选参数：用于生成嵌入向量的模型。若未提供，将使用内部选定的默认值。	否
prefilter_column_names	array	向量搜索查询中用于预过滤的列。	否
distance_func	string	用于比较向量的距离函数（允许输入：'cosine'、'ip'、'l2'、'l1'）。	否
quantization	string	用于创建向量索引的量化方式（允许输入：'none'、'halfvec'、'bit'）。	否
memory_budget_kb	integer	索引构建时可占用的最大内存大小（KB）。	否
target_recall	float	用户希望该索引在标准向量查询中达到的召回率。	否
target_top_k	integer	查询需要返回的Top-K值。	否
tune_vector_index	boolean	指定是否需要对索引进行自动调优的布尔参数。	否

execute_sql

Use this tool to execute a single SQL statement.

使用此工具执行单个SQL语句。

Parameters

参数

Name	Type	Description	Required	Default
sql	string	The sql to execute.	Yes

名称	类型	描述	必填	默认值
sql	string	要执行的SQL语句。	是

generate_query

This tool generates optimized SQL queries for vector search by leveraging the metadata and vector specifications defined in a specific spec_id. It may return a single query or a sequence of multiple SQL queries that can be executed sequentially. Use this tool when a user wants to perform semantic or similarity searches on their data. It serves as the primary actionable tool to invoke for generating the executable SQL required to retrieve relevant results based on vector similarity. The 'execute_sql' tool can be used as a follow-up action after invoking this tool.

该工具利用特定spec_id中定义的元数据和向量规格，生成优化的向量搜索SQL查询。它可能返回单个查询或多个可按顺序执行的SQL查询序列。当用户想要对数据执行语义搜索或相似度搜索时，可使用此工具。这是生成基于向量相似度检索相关结果所需可执行SQL的主要工具。调用此工具后，可使用

execute_sql

工具作为后续操作。

Parameters

参数

Name	Type	Description	Required
spec_id	string	Generate the vector query corresponding to this vector spec.	No
table_name	string	Generate the vector query corresponding to this table (in case of a single spec defined on the table).	No
schema_name	string	Schema name for the table related to the vector query generation.	No
column_name	string	text_column_name or vector_column_name of the spec to identify the exact spec in case there are multiple specs defined on a table.	No
search_text	string	Text search for which query needs to be generated. Embeddings are generated using the model defined in the vector spec.	No
search_vector	string	Vector for which query needs to be generated. Only one of search_text or search_vector must be populated.	No
output_column_names	array	Column names to retrieve in the output search query. Defaults to retrieving all columns.	No
top_k	integer	Number of nearest neighbors to be returned in the vector search query. Defaults to 10.	No
filter_expressions	array	Any filter expressions to be applied on the vector search query.	No
target_recall	float	The recall that the user would like to target with the given query. Overrides the spec-level target_recall.	No
iterative_index_search	boolean	Perform iterative index search for filtered queries to ensure enough results are returned.	No

名称	类型	描述	必填
spec_id	string	生成与此向量规格对应的向量查询。	否
table_name	string	生成与此表对应的向量查询（适用于表上仅定义了单个规格的情况）。	否
schema_name	string	与向量查询生成相关的表所属的模式名。	否
column_name	string	当表上定义了多个规格时，用于标识具体规格的text_column_name或vector_column_name。	否
search_text	string	需要生成查询的文本搜索内容。将使用向量规格中定义的模型生成嵌入向量。	否
search_vector	string	需要生成查询的向量。search_text和search_vector必须且只能填写其中一个。	否
output_column_names	array	搜索查询结果中需要返回的列名。默认返回所有列。	否
top_k	integer	向量搜索查询中需要返回的最近邻数量。默认值为10。	否
filter_expressions	array	要应用于向量搜索查询的过滤表达式。	否
target_recall	float	用户希望该查询达到的召回率。将覆盖规格级别的target_recall。	否
iterative_index_search	boolean	对过滤后的查询执行迭代索引搜索，以确保返回足够的结果。	否

modify_spec

This tool modifies an existing vector specification (identified by a required spec_id) with new parameters or overrides. Upon modification, it automatically recalculates and refreshes the list of generated SQL recommendations to match the updated requirements. This tool provides a way to modify column(s) in the vector spec before applying and taking action on the recommendations. While highly customizable, any optional parameters left unspecified will use internally determined defaults optimized for the specific workload. Use this tool to modify configurations established via 'define_spec' tool such as adjusting target recall, embedding models, or quantization settings, etc.

该工具使用新参数或覆盖现有参数来修改现有向量规格（由必填的spec_id标识）。修改后，它会自动重新计算并刷新生成的SQL建议列表，以匹配更新后的需求。此工具提供了在应用建议并采取行动前修改向量规格中列的方法。虽然高度可自定义，但任何未指定的可选参数都将使用针对特定工作负载优化的内部默认值。可使用此工具修改通过

define_spec

工具建立的配置，例如调整目标召回率、嵌入模型或量化设置等。

Parameters

参数

Name	Type	Description	Required
spec_id	string	Unique ID for the vector spec you want to modify.	Yes
table_name	string	Modify the table name on which vector workload needs to be set up.	No
schema_name	string	Modify the schema containing the given table.	No
vector_column_name	string	Modify the column name for the column with vector embeddings.	No
text_column_name	string	Modify the column name for the column with text on which vector search needs to be set up.	No
vector_index_type	string	Modify the type of the vector index to be created (Allowed inputs: 'hnsw', 'ivfflat', 'scann').	No
embeddings_available	boolean	Modify whether vector embeddings are already available in the table.	No
num_vectors	integer	Modify the number of vectors expected in the dataset.	No
dimensionality	integer	Modify the dimensionality of the vectors or embedding model.	No
embedding_model	string	Modify the model used for generating embeddings.	No
prefilter_column_names	array	Modify the column(s) based on which prefiltering will happen in vector search queries.	No
distance_func	string	Modify the distance function to be used for comparing vectors (Allowed inputs: 'cosine', 'ip', 'l2', 'l1').	No
quantization	string	Modify the quantization to be used for creating the vector indexes (Allowed inputs: 'none', 'halfvec', 'bit').	No
memory_budget_kb	integer	Modify the maximum size that the index can consume in memory while building.	No
target_recall	float	Modify the recall that the user would like to target with the given index.	No
target_top_k	integer	Modify the Top-K matching values that need to be retrieved for the given query.	No
tune_vector_index	boolean	Modify whether to tune vector index build and search parameters.	No

名称	类型	描述	必填
spec_id	string	要修改的向量规格的唯一ID。	是
table_name	string	修改需要设置向量工作负载的表名。	否
schema_name	string	修改包含该表的模式。	否
vector_column_name	string	修改存储向量嵌入的列名。	否
text_column_name	string	修改需要设置向量搜索的文本列名。	否
vector_index_type	string	修改要创建的向量索引类型（允许输入：'hnsw'、'ivfflat'、'scann'）。	否
embeddings_available	boolean	修改表中是否已存在向量嵌入。	否
num_vectors	integer	修改数据集中预期的向量数量。	否
dimensionality	integer	修改向量或嵌入模型的维度。	否
embedding_model	string	修改用于生成嵌入向量的模型。	否
prefilter_column_names	array	修改向量搜索查询中用于预过滤的列。	否
distance_func	string	修改用于比较向量的距离函数（允许输入：'cosine'、'ip'、'l2'、'l1'）。	否
quantization	string	修改用于创建向量索引的量化方式（允许输入：'none'、'halfvec'、'bit'）。	否
memory_budget_kb	integer	修改索引构建时可占用的最大内存大小。	否
target_recall	float	修改用户希望该索引达到的召回率。	否
target_top_k	integer	修改查询需要返回的Top-K匹配值。	否
tune_vector_index	boolean	修改是否需要调优向量索引的构建和搜索参数。	否