MySQL
| PostgreSQL
| SQL Server
本页面详细介绍了所有可用的向量辅助函数，以及它们的必需参数和可选参数。
vector_assist.define_spec
定义新的向量规范（或向量规范），并返回升级向量工作负载所需的建议。此函数会应用用户提供的规范来生成推荐内容。
函数
CREATE OR REPLACE FUNCTION vector_assist.define_spec(
spec_id TEXT DEFAULT NULL,
table_name TEXT,
schema_name TEXT DEFAULT NULL,
vector_column_name TEXT DEFAULT NULL,
text_column_name TEXT DEFAULT NULL,
vector_index_type TEXT DEFAULT NULL, -- Allowed: 'hnsw', 'ivfflat'
embeddings_available BOOL DEFAULT NULL,
embedding_model TEXT DEFAULT NULL,
num_vectors INT DEFAULT NULL,
dimensionality INT DEFAULT NULL,
distance_func TEXT DEFAULT NULL, -- Allowed: 'cosine', 'ip', 'l2', 'l1'
quantization TEXT DEFAULT NULL, -- Allowed: 'none', 'halfvec', 'bit'
prefilter_column_names TEXT[] DEFAULT NULL,
memory_budget_kb INT DEFAULT NULL, -- In KB
target_recall FLOAT DEFAULT NULL,
target_top_k INT DEFAULT NULL,
tune_vector_index BOOL DEFAULT FALSE, -- Set to true if target_recall is set
)
RETURNS SETOF vector_assist.RECOMMENDATIONS;
参数
| 参数 | 是否必需？ | 说明 |
|---|---|---|
spec_id |
必需（自动生成） | 您定义的向量规范的唯一 ID。 |
table_name |
是否必需？ | 要在向量工作负载设置中使用的表名称。 |
schema_name |
可选 | 包含要在向量工作负载中使用的表的架构。 系统会根据架构搜索路径自动推断架构。 |
vector_column_name |
可选或必填 | 包含向量嵌入的列的列名称。 如果您使用多个向量列，且未声明 text_column_name，则此列为必需列。如果您只使用一个向量列，则此参数为可选参数。 |
text_column_name |
可选或必填 | 文本列的列名称。如果您的向量工作负载需要从文本列生成嵌入内容，则此参数是必需的。 如果 vector_column_name 参数为 NULL 且没有其他向量列，则此列是必需的。此参数使用 google_ml_integration 扩展程序从给定的文本列生成嵌入。 |
vector_index_type |
可选 | 向量索引的类型。可接受的值包括：
|
embeddings_available |
可选 | 一个布尔值，用于检查所选表中是否存在向量嵌入。
如果未检测到任何向量列，并且设置了 text_column_name 参数，则此字段设置为 FALSE。 |
embedding_model |
可选或必填 | 用于生成嵌入的 google_ml.models 中的模型 ID。除非 embeddings_available 参数为 FALSE 或 NULL，否则此字段是可选字段。 |
num_vectors |
可选 | 表中的向量数。 |
dismensionality |
可选 | 指定向量的维度。 |
distance_func |
可选 | 用于比较向量的距离函数。可接受的值包括 cosine、ip、l2 或 l1。 |
quantization |
可选 | 向量索引的量化。可接受的值包括 none、halfvec 或 bit。 |
prefilter_column_names |
可选 | 为指定列创建索引以进行预过滤。这可能有助于提高对该列应用高选择性过滤条件的查询的性能。 |
memory_budget_kb |
可选 | 用于构建索引的最大内存（以 KB 为单位）。 |
target_recall |
可选 | 标准向量查询的目标召回率。 |
target_top_k |
可选 | 要检索的用于计算召回率的 top-K 匹配值。
如果指定了 target_recall 参数，则使用此值。 |
tune_vector_index |
可选 | 对工作负载中的向量索引进行调优。如果启用，向量辅助功能会使用向量规范自动调整向量索引或搜索查询，并计算最佳数据库和索引参数。可接受的值包括 TRUE 或 FALSE。 |
返回值
返回一个建议表，其中包含必须应用的建议，以设置所请求的向量工作负载。每行都是一条建议，其中包含可执行的 SQL 查询以及有关为何要应用该建议的详细说明。可以使用 apply_recommendation() 函数应用建议。
“建议”表包含以下各列：
| 列名 | 类型 | 说明 |
|---|---|---|
recommendation_id |
文本 | 建议的 ID。系统会使用此 ID 应用建议。 |
vector_spec_id |
文本 | 与建议关联的向量规范的 ID。 |
table_name |
文本 | 与建议关联的表名称。 |
schema_name |
文本 | 包含指定表的架构名称。 |
query |
文本 | 为实现建议结果而要运行的可执行 SQL 查询。 |
recommendation |
文本 | 建议的说明，包括应用建议后的预期结果。此列还包含建议的原因和依据。您可以根据需要使用此上下文来调整查询，并重新生成建议。 |
applied |
布尔值 | 显示建议是否已采纳。 |
modified |
布尔值 | 显示建议是否已被用户修改。 |
created_at |
有时区的时间戳 | 生成建议的时间，格式为 timestamp with time zone。例如 2024-07-18 09:00:00-08。 |
vector_assist.list_specs
返回给定表和列的当前向量规范。
函数
CREATE OR REPLACE FUNCTION vector_assist.list_specs(
table_name TEXT,
column_name TEXT DEFAULT NULL
)
RETURNS SETOF vector_assist.VECTOR_SPECS
参数
| 参数 | 是否必需？ | 说明 |
|---|---|---|
table_name |
是否必需？ | 要检索向量规范的表的名称。 |
column_name |
可选 | 在返回规范之前要过滤的列名称。如果指定了列名称，则返回包含与此列名称匹配的文本或向量列名称的规范。 |
返回值
返回指定表（以及可选的列名称）的规范表。
vector_assist.modify_spec
修改现有向量规范。修改向量规范后，系统会根据新规范重新生成关联的建议。
函数
CREATE OR REPLACE FUNCTION vector_assist.modify_spec(
spec_id TEXT,
table_name TEXT DEFAULT NULL,
schema_name TEXT DEFAULT NULL,
vector_column_name TEXT DEFAULT NULL,
text_column_name TEXT DEFAULT NULL,
vector_index_type TEXT DEFAULT NULL,
embeddings_available BOOL DEFAULT NULL,
num_vectors INT DEFAULT NULL,
dimensionality INT DEFAULT NULL,
embedding_model TEXT DEFAULT NULL,
prefilter_column_names TEXT[] DEFAULT NULL,
distance_func TEXT DEFAULT NULL,
quantization TEXT DEFAULT NULL,
memory_budget_kb INT DEFAULT NULL,
target_recall FLOAT DEFAULT NULL,
target_top_k INT DEFAULT NULL,
tune_vector_index BOOL DEFAULT NULL
)
RETURNS SETOF vector_assist.RECOMMENDATIONS
参数
| 参数 | 是否必需？ | 说明 |
|---|---|---|
spec_id |
必需（自动生成） | 您定义的向量规范的唯一 ID。 |
table_name |
是否必需？ | 要在向量工作负载设置中使用的表名称。 |
schema_name |
可选 | 包含要在向量工作负载中使用的表的架构。 系统会根据架构搜索路径自动推断架构。 |
vector_column_name |
可选或必填 | 包含向量嵌入的列的列名称。 如果您使用多个向量列，且未声明 text_column_name，则此列为必需列。如果您只使用一个向量列，则此参数为可选参数。 |
text_column_name |
可选或必填 | 文本列的列名称。如果您的向量工作负载需要从文本列生成嵌入内容，则此参数是必需的。 如果 vector_column_name 参数为 NULL 且没有其他向量列，则此列是必需的。此参数使用 google_ml_integration 扩展程序从给定的文本列生成嵌入。 |
vector_index_type |
可选 | 向量索引的类型。可接受的值包括：
|
embeddings_available |
可选 | 一个布尔值，用于检查所选表中是否存在向量嵌入。
如果未检测到任何向量列，并且设置了 text_column_name 参数，则此字段设置为 FALSE。 |
embedding_model |
可选或必填 | 用于生成嵌入的 google_ml.models 中的模型 ID。除非 embeddings_available 参数为 FALSE 或 NULL，否则此字段是可选字段。 |
num_vectors |
可选 | 表中的向量数。 |
dismensionality |
可选 | 指定向量的维度。 |
distance_func |
可选 | 用于比较向量的距离函数。可接受的值包括 cosine、ip、l2 或 l1。 |
quantization |
可选 | 向量索引的量化。可接受的值包括 none、halfvec 或 bit。 |
prefilter_column_names |
可选 | 标识在向量搜索查询中可用于预过滤的列。 |
memory_budget_kb |
可选 | 用于构建索引的最大内存（以 KB 为单位）。 |
target_recall |
可选 | 标准向量查询的目标召回率。 |
target_top_k |
可选 | 要检索的用于计算召回率的 top-K 匹配值。
如果指定了 target_recall 参数，则使用此值。 |
tune_vector_index |
可选 | 对工作负载中的向量索引进行调优。如果启用，向量辅助功能会使用向量规范自动调整向量索引或搜索查询，并计算最佳数据库和索引参数。可接受的值包括 TRUE 或 FALSE。 |
返回值
返回一个更新后的建议表，该表必须应用于设置所请求的向量工作负载。每行都是一条建议，其中包含可执行的 SQL 查询以及有关为何要应用该建议的详细说明。您可以使用 apply_recommendation() 函数采纳建议。
“建议”表包含以下各列：
| 列名 | 类型 | 说明 |
|---|---|---|
recommendation_id |
文本 | 建议的 ID。系统会使用此 ID 应用建议。 |
vector_spec_id |
文本 | 与建议关联的向量规范的 ID。 |
table_name |
文本 | 与建议关联的表名称。 |
schema_name |
文本 | 包含指定表的架构名称。 |
query |
文本 | 为实现建议结果而要运行的可执行 SQL 查询。 |
recommendation |
文本 | 建议的说明，包括应用建议后的预期结果。此列还包含建议的原因和依据。您可以根据需要使用此上下文来调整查询，并重新生成建议。 |
applied |
布尔值 | 显示建议是否已采纳。 |
modified |
布尔值 | 显示建议是否已被用户修改。 |
created_at |
带时区的时间戳 | 生成建议的时间。 |
vector_assist.get_recommendations
返回与特定向量 spec_id 关联的建议。
函数
CREATE OR REPLACE FUNCTION vector_assist.get_recommendations (
spec_id TEXT
)
RETURNS SETOF vector_assist.RECOMMENDATIONS;
参数
| 参数 | 是否必需？ | 说明 |
|---|---|---|
spec_id |
是否必需？ | 获取指定向量 spec_id 的建议。 |
返回值
返回所请求的建议表。
“建议”表包含以下各列：
| 列名 | 类型 | 说明 |
|---|---|---|
recommendation_id |
文本 | 建议的 ID。系统会使用此 ID 应用建议。 |
vector_spec_id |
文本 | 与建议关联的向量规范的 ID。 |
table_name |
文本 | 与建议关联的表名称。 |
schema_name |
文本 | 包含指定表的架构名称。 |
query |
文本 | 为实现建议结果而要运行的可执行 SQL 查询。 |
recommendation |
文本 | 建议的说明，包括应用建议后的预期结果。此列还包含建议的原因和依据。您可以根据需要使用此上下文来调整查询，并重新生成建议。 |
applied |
布尔值 | 显示建议是否已采纳。 |
modified |
布尔值 | 显示建议是否已被用户修改。 |
created_at |
带时区的时间戳 | 生成建议的时间。 |
vector_assist.apply_recommendation
使用 recommendation_id 应用单个建议。
函数
CREATE OR REPLACE FUNCTION vector_assist.get_recommendations (
spec_id TEXT
)
RETURNS SETOF vector_assist.RECOMMENDATIONS;
参数
| 参数 | 是否必需？ | 说明 |
|---|---|---|
recommenation_id |
是否必需？ | 要应用的向量推荐的 ID。 |
返回值
返回一个布尔值，用于确认建议是否已成功应用，并将 vector_assist.RECOMMENDATIONS 表列 applied 更新为 TRUE。
如果向量辅助功能无法应用建议，则会在失败时显示错误消息。
vector_assist.apply_spec
应用与特定向量 spec_id 或表名称关联的所有建议。此函数会遍历所有建议，并针对每条建议运行 vector_assist.apply_recommendation 函数。
必须指定 spec_id 或 table_name 才能运行函数。
函数
CREATE OR REPLACE FUNCTION vector_assist.apply_spec(
spec_id TEXT DEFAULT NULL,
table_name TEXT DEFAULT NULL,
schema_name TEXT DEFAULT NULL,
column_name TEXT DEFAULT NULL -- text_column_name or vector_column_name
)
RETURNS BOOLEAN;
参数
| 参数 | 是否必需？ | 说明 |
|---|---|---|
spec_id |
可选 | 针对给定的向量 spec_id 应用所有建议。
|
table_name |
可选 | 应用指定表的所有建议。 |
schema_name |
可选 | 包含指定表的架构。 |
column_name |
可选 | 用于标识当表包含多个向量规范时要使用的 text_column_name 或 vector_column_name。 |
返回值
返回一个布尔值，用于确认是否已成功应用所有建议，并将 vector_assist.RECOMMENDATIONS 表列 applied 中的值针对所有建议设置为 TRUE。
如果向量辅助功能无法应用建议，则会在失败时显示错误消息。
vector_assist.modify_recommendation
修改特定建议的查询，并将关联建议的 vector_assist.RECOMMENDATIONS 表中的 modified 字段设置为 TRUE。
函数
CREATE OR REPLACE FUNCTION vector_assist.modify_recommendation(
recommendation_id TEXT,
modified_query TEXT
)
RETURNS BOOLEAN;
参数
| 参数 | 是否必需？ | 说明 |
|---|---|---|
recommendation_id |
是否必需？ | 要修改的建议的 ID。 |
modified_query |
是否必需？ | 用户修改的推荐 SQL 查询。 |
返回值
返回一个布尔值，用于确认建议是否已成功更新，并将 vector_assist.RECOMMENDATIONS 表列 modified 设置为 TRUE。
如果向量辅助功能无法更新推荐，则会在失败时显示错误消息。
vector_assist.generate_query
根据定义的向量规范和搜索参数生成优化的向量搜索查询。此函数可能会调整 ef_search 值以满足设置的 target_recall（如果适用）。
函数
CREATE OR REPLACE FUNCTION vector_assist.generate_query(
spec_id TEXT DEFAULT NULL,
table_name TEXT DEFAULT NULL,
schema_name TEXT DEFAULT NULL,
column_name TEXT DEFAULT NULL, -- text_column_name or vector_column_name of the spec
search_text TEXT DEFAULT NULL,
search_vector VECTOR DEFAULT NULL, -- e.g. '[1.0,2.0,3.0]'::vector
output_column_names TEXT[] DEFAULT NULL, -- Columns to retrieve, NULL for SELECT *
top_k INT DEFAULT NULL,
filter_expressions TEXT[] DEFAULT NULL,
target_recall FLOAT DEFAULT NULL, -- Inherited from spec, can be overridden
iterative_index_search BOOL DEFAULT NULL
)
RETURNS TEXT; -- Returns the text representing the search query
参数
| 参数 | 是否必需？ | 说明 |
|---|---|---|
spec_id |
可选 | 指定要为其生成查询的 spec_id。 |
table_name |
可选 | 指定在未提供 spec_id 时要生成搜索查询的表名称。如果表包含多个规范，则该参数会返回错误。 |
column_name |
可选 | 如果未提供 spec_id，则指定要生成搜索查询的列名称。如果列包含多个规范，则该参数会返回错误。column_name 可能是 text_column_name 或 vector_column_name。 |
output_column_name |
可选 | 要在输出查询中检索的列名称。如需检索所有列，请将此参数设置为 NULL。 |
search_text |
可选 | 要为其生成嵌入的搜索文本。需要向量规范中的 embedding_model。嵌入是使用规范中的模型生成的。您只能设置 search_text 或 search_vector 参数。 |
search_vector |
可选 | 搜索查询的向量。您只能设置 search_text 或 search_vector 参数 |
top_k |
可选 | 要返回的最近邻数量。 |
filter_expressions |
可选 | 要在搜索查询中应用的过滤表达式。过滤条件可以应用于表中的字段，例如价格 < 100。 |
iterative_index_search |
可选 | 设置是否针对过滤后的查询执行迭代索引搜索。此参数会替换向量规范中的设置。 |
target_recall |
可选 | 仅适用于搜索查询的目标召回率。此参数会替换向量规范中的设置并调整 ef_search。 |
返回值
返回包含指定参数的向量搜索查询的文本。 您可以执行此查询，也可以保存此查询以供日后运行。
vector_assist.evaluate_query_recall
评估向量索引针对给定查询的召回率。此函数使用 JSON 字符串中的数据库和索引配置作为输入。
函数
CREATE OR REPLACE FUNCTION vector_assist.evaluate_query_recall(
IN ann_query text,
IN vector_search_configurations json DEFAULT NULL,
OUT recall float,
OUT ann_execution_time float,
OUT ground_truth_execution_time float,
OUT index_type text)
RETURNS RECORD
参数
| 参数 | 是否必需？ | 说明 |
|---|---|---|
ann_query |
是否必需？ | 需要评估召回率的 SQL 查询。此查询应为 pgvector ANN 查询。 |
vector_search_configurations |
可选 | 可为 ANN 查询设置的配置。此参数必须采用 JSON 格式。 |
返回值
返回一个表，用于评估给定查询的向量索引的召回率。
该表包含以下列：
| 列名 | 类型 | 说明 |
|---|---|---|
recall |
浮点数 | 索引返回的、真正最近邻向量的百分比。此指标用于量化搜索质量。 借助此函数，您可以对参数进行调优以返回预期的向量查询召回率结果。 |
ann_execution_time |
浮点数 | 使用索引扫描执行向量查询所需的时间。 |
ground_truth_execution_time |
浮点数 | 使用顺序扫描运行查询所需的时间。 |
示例
以下示例评估了 HNSW 索引的召回率，并替换了 HNSW.ef_search 配置参数：
SELECT * FROM vector_assist.evaluate_query_recall(
ann_query => 'SELECT id FROM items ORDER BY embedding <=> ''[1,2,3]'' LIMIT 10',
vector_search_configurations => '{"hnsw.ef_search": 30}'
);