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 が宣言されていない場合、この列は必須です。ベクトル列を 1 つだけ使用する場合は、このパラメータは省略可能です。 |
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 が宣言されていない場合、この列は必須です。ベクトル列を 1 つだけ使用する場合は、このパラメータは省略可能です。 |
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 |
タイムゾーン付きのタイムスタンプ | 推奨事項が生成された時刻。 |
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
定義されたベクトル仕様と検索パラメータに基づいて、最適化されたベクトル検索クエリを生成します。この関数は、必要に応じて、設定された target_recall を満たすように ef_search 値を調整する場合があります。
関数
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}'
);