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 |
選用 | 要擷取的 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 |
選填或必填 | 要用於生成嵌入的模型 ID，來自
google_ml.models
。除非 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 |
選用 | 要擷取的 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}'
);