Questa pagina fornisce informazioni dettagliate su tutte le funzioni di assistenza vettoriale disponibili e sui relativi parametri obbligatori e facoltativi.
vector_assist.define_spec
Definisce una nuova specifica vettoriale, o vector spec, e restituisce i suggerimenti necessari per migliorare il workload vettoriale. Questa funzione applica le specifiche fornite dall'utente per generare i suggerimenti.
Funzione
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;
Parametri
| Parametro | Obbligatorio? | Descrizione |
|---|---|---|
spec_id |
Obbligatorio (generato automaticamente) | Un ID univoco per la specifica vettoriale che definisci. |
table_name |
Obbligatorio? | Il nome della tabella da utilizzare nella configurazione del workload vettoriale. |
schema_name |
Facoltativo | Lo schema contenente la tabella da utilizzare nel workload vettoriale. Lo schema viene dedotto automaticamente in base al percorso di ricerca dello schema. |
vector_column_name |
Obbligatorio o facoltativo | Il nome della colonna contenente i vector embedding. Questa colonna è obbligatoria se utilizzi più di una colonna vettoriale e text_column_name non è dichiarato. Se utilizzi una sola colonna vettoriale, questo parametro è facoltativo. |
text_column_name |
Obbligatorio o facoltativo | Il nome della colonna di testo. Se il workload vettoriale richiede la generazione di embedding da una colonna di testo, questo parametro è obbligatorio. Questa colonna è obbligatoria se il parametro vector_column_name è
NULL e non sono presenti altre colonne vettoriali.Questo parametro utilizza l'estensione google_ml_integration per generare embedding dalla colonna di testo specificata. |
vector_index_type |
Facoltativo | Il tipo di indice vettoriale. I valori accettati includono:
|
embeddings_available |
Facoltativo | Un valore booleano che verifica se i vector embedding esistono nella tabella selezionata.
Questo campo è impostato su FALSE se non vengono rilevate colonne vettoriali e il parametro text_column_name è impostato. |
embedding_model |
Obbligatorio o facoltativo | L'ID modello di google_ml.models da utilizzare per generare gli embedding. Questo campo è facoltativo, a meno che il parametro embeddings_available non sia FALSE o NULL. |
num_vectors |
Facoltativo | Il numero di vettori nella tabella. |
dismensionality |
Facoltativo | La dimensione dei vettori specificati. |
distance_func |
Facoltativo | La funzione di distanza da utilizzare per confrontare il vettore. I valori accettati includono cosine, ip, l2 o l1. |
quantization |
Facoltativo | La quantizzazione per gli indici vettoriali. I valori accettati includono none, halfvec o bit. |
prefilter_column_names |
Facoltativo | Crea un indice per la colonna specificata per il pre-filtraggio. Ciò potrebbe contribuire a migliorare le prestazioni per le query con un filtro ad alta selettività sulla colonna. |
memory_budget_kb |
Facoltativo | La memoria massima (in kB) per la creazione dell'indice. |
target_recall |
Facoltativo | Il recall target per le query vettoriali standard. |
target_top_k |
Facoltativo | I valori corrispondenti top-K da recuperare per il calcolo del richiamo.
Questo valore viene utilizzato se viene specificato il parametro target_recall. |
tune_vector_index |
Facoltativo | Ottimizza gli indici vettoriali nel tuo workload. Se abilitato, l'assistente vettoriale ottimizza automaticamente l'indice vettoriale o la query di ricerca utilizzando la specifica vettoriale e calcola i parametri ottimali del database e dell'indice. I valori accettabili includono TRUE o FALSE. |
Valore restituito
Restituisce una tabella di suggerimenti che devono essere applicati per configurare il workload vettoriale richiesto. Ogni riga è un singolo suggerimento che contiene una query SQL eseguibile e una spiegazione dettagliata del motivo per cui applicare il suggerimento. Il suggerimento può essere applicato utilizzando la funzione apply_recommendation().
La tabella dei suggerimenti contiene le seguenti colonne:
| Nome colonna | Tipo | Descrizione |
|---|---|---|
recommendation_id |
Testo | L'ID del suggerimento. Il suggerimento viene applicato utilizzando questo ID. |
vector_spec_id |
Testo | L'ID della specifica vettoriale associata al suggerimento. |
table_name |
Testo | Il nome della tabella associata al suggerimento. |
schema_name |
Testo | Il nome dello schema contenente la tabella specificata. |
query |
Testo | La query SQL eseguibile da eseguire per ottenere il risultato del suggerimento. |
recommendation |
Testo | La spiegazione del suggerimento, incluso il risultato previsto una volta applicato il suggerimento. Questa colonna contiene anche il motivo e la motivazione del suggerimento. Puoi utilizzare questo contesto per ottimizzare la query in base alle tue esigenze e rigenerare i suggerimenti. |
applied |
Booleano | Indica se il consiglio è stato applicato. |
modified |
Booleano | Indica se il suggerimento è stato modificato dall'utente. |
created_at |
Timestamp con fuso orario | L'ora in cui è stato generato il suggerimento nel formato timestamp with time zone. Ad esempio,
2024-07-18 09:00:00-08. |
vector_assist.list_specs
Restituisce la specifica vettoriale corrente per una tabella e una colonna specificate.
Funzione
CREATE OR REPLACE FUNCTION vector_assist.list_specs(
table_name TEXT,
column_name TEXT DEFAULT NULL
)
RETURNS SETOF vector_assist.VECTOR_SPECS
Parametri
| Parametro | Obbligatorio? | Descrizione |
|---|---|---|
table_name |
Obbligatorio? | Il nome della tabella per cui viene recuperata la specifica vettoriale. |
column_name |
Facoltativo | Il nome della colonna in base alla quale filtrare la tabella prima di restituire la specifica. Se il nome della colonna è specificato, vengono restituite le specifiche che contengono nomi di colonne di testo o vettoriali corrispondenti a questo nome di colonna. |
Valore restituito
Restituisce una tabella di specifiche per la tabella specificata e, facoltativamente, il nome della colonna.
vector_assist.modify_spec
Modifica una specifica vettoriale esistente. Quando la specifica vettoriale viene modificata, i suggerimenti associati vengono rigenerati in base alle nuove specifiche.
Funzione
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
Parametri
| Parametro | Obbligatorio? | Descrizione |
|---|---|---|
spec_id |
Obbligatorio (generato automaticamente) | Un ID univoco per la specifica vettoriale che definisci. |
table_name |
Obbligatorio? | Il nome della tabella da utilizzare nella configurazione del workload vettoriale. |
schema_name |
Facoltativo | Lo schema contenente la tabella da utilizzare nel workload vettoriale. Lo schema viene dedotto automaticamente in base al percorso di ricerca dello schema. |
vector_column_name |
Obbligatorio o facoltativo | Il nome della colonna contenente i vector embedding. Questa colonna è obbligatoria se utilizzi più di una colonna vettoriale e text_column_name non è dichiarato. Se utilizzi una sola colonna vettoriale, questo parametro è facoltativo. |
text_column_name |
Obbligatorio o facoltativo | Il nome della colonna di testo. Se il workload vettoriale richiede la generazione di embedding da una colonna di testo, questo parametro è obbligatorio. Questa colonna è obbligatoria se il parametro vector_column_name è
NULL e non sono presenti altre colonne vettoriali.Questo parametro utilizza l'estensione google_ml_integration per generare embedding dalla colonna di testo specificata. |
vector_index_type |
Facoltativo | Il tipo di indice vettoriale. I valori accettati includono:
|
embeddings_available |
Facoltativo | Un valore booleano che verifica se i vector embedding esistono nella tabella selezionata.
Questo campo è impostato su FALSE se non vengono rilevate colonne vettoriali e il parametro text_column_name è impostato. |
embedding_model |
Obbligatorio o facoltativo | L'ID modello di google_ml.models da utilizzare per generare gli embedding. Questo campo è facoltativo, a meno che il parametro embeddings_available non sia FALSE o NULL. |
num_vectors |
Facoltativo | Il numero di vettori nella tabella. |
dismensionality |
Facoltativo | La dimensione dei vettori specificati. |
distance_func |
Facoltativo | La funzione di distanza da utilizzare per confrontare il vettore. I valori accettati includono cosine, ip, l2 o l1. |
quantization |
Facoltativo | La quantizzazione per gli indici vettoriali. I valori accettati includono none, halfvec o bit. |
prefilter_column_names |
Facoltativo | Identifica le colonne rese disponibili per il pre-filtraggio nelle query di ricerca vettoriale. |
memory_budget_kb |
Facoltativo | La memoria massima (in kB) per la creazione dell'indice. |
target_recall |
Facoltativo | Il recall target per le query vettoriali standard. |
target_top_k |
Facoltativo | I valori corrispondenti top-K da recuperare per il calcolo del richiamo.
Questo valore viene utilizzato se viene specificato il parametro target_recall. |
tune_vector_index |
Facoltativo | Ottimizza gli indici vettoriali nel tuo workload. Se abilitato, l'assistente vettoriale ottimizza automaticamente l'indice vettoriale o la query di ricerca utilizzando la specifica vettoriale e calcola i parametri ottimali del database e dell'indice. I valori accettabili includono TRUE o FALSE. |
Valore restituito
Restituisce una tabella aggiornata di suggerimenti che devono essere applicati per configurare il workload vettoriale richiesto. Ogni riga è un singolo suggerimento che contiene una query SQL eseguibile e una spiegazione dettagliata del motivo per cui applicare il suggerimento. Il suggerimento può essere applicato utilizzando la funzione apply_recommendation().
La tabella dei suggerimenti contiene le seguenti colonne:
| Nome colonna | Tipo | Descrizione |
|---|---|---|
recommendation_id |
Testo | L'ID del suggerimento. Il suggerimento viene applicato utilizzando questo ID. |
vector_spec_id |
Testo | L'ID della specifica vettoriale associata al suggerimento. |
table_name |
Testo | Il nome della tabella associata al suggerimento. |
schema_name |
Testo | Il nome dello schema contenente la tabella specificata. |
query |
Testo | La query SQL eseguibile da eseguire per ottenere il risultato del suggerimento. |
recommendation |
Testo | La spiegazione del suggerimento, incluso il risultato previsto una volta applicato il suggerimento. Questa colonna contiene anche il motivo e la motivazione del suggerimento. Puoi utilizzare questo contesto per ottimizzare la query in base alle tue esigenze e rigenerare i suggerimenti. |
applied |
Booleano | Indica se il consiglio è stato applicato. |
modified |
Booleano | Indica se il suggerimento è stato modificato dall'utente. |
created_at |
Timestamp con fuso orario | La data e l'ora in cui è stato generato il suggerimento. |
vector_assist.get_recommendations
Restituisce i suggerimenti associati a un vettore specifico spec_id.
Funzione
CREATE OR REPLACE FUNCTION vector_assist.get_recommendations (
spec_id TEXT
)
RETURNS SETOF vector_assist.RECOMMENDATIONS;
Parametri
| Parametro | Obbligatorio? | Descrizione |
|---|---|---|
spec_id |
Obbligatorio? | Recupera i suggerimenti per il vettore spec_id specificato. |
Valore restituito
Restituisce una tabella dei suggerimenti richiesti.
La tabella dei suggerimenti contiene le seguenti colonne:
| Nome colonna | Tipo | Descrizione |
|---|---|---|
recommendation_id |
Testo | L'ID del suggerimento. Il suggerimento viene applicato utilizzando questo ID. |
vector_spec_id |
Testo | L'ID della specifica vettoriale associata al suggerimento. |
table_name |
Testo | Il nome della tabella associata al suggerimento. |
schema_name |
Testo | Il nome dello schema contenente la tabella specificata. |
query |
Testo | La query SQL eseguibile da eseguire per ottenere il risultato del suggerimento. |
recommendation |
Testo | La spiegazione del suggerimento, incluso il risultato previsto una volta applicato il suggerimento. Questa colonna contiene anche il motivo e la motivazione del suggerimento. Puoi utilizzare questo contesto per ottimizzare la query in base alle tue esigenze e rigenerare i suggerimenti. |
applied |
Booleano | Indica se il consiglio è stato applicato. |
modified |
Booleano | Indica se il suggerimento è stato modificato dall'utente. |
created_at |
Timestamp con fuso orario | La data e l'ora in cui è stato generato il suggerimento. |
vector_assist.apply_recommendation
Applica un singolo suggerimento utilizzando recommendation_id.
Funzione
CREATE OR REPLACE FUNCTION vector_assist.get_recommendations (
spec_id TEXT
)
RETURNS SETOF vector_assist.RECOMMENDATIONS;
Parametri
| Parametro | Obbligatorio? | Descrizione |
|---|---|---|
recommenation_id |
Obbligatorio? | L'ID del suggerimento vettoriale da applicare. |
Valore restituito
Restituisce un valore booleano che conferma se un suggerimento è stato applicato correttamente
e aggiorna la colonna applied della tabella vector_assist.RECOMMENDATIONS in
TRUE.
Se l'assistente vettoriale non è in grado di applicare il suggerimento, genera un messaggio di errore.
vector_assist.apply_spec
Applica tutti i suggerimenti associati a un vettore spec_id o a un nome di tabella specifico. Questa funzione esamina tutti i suggerimenti ed esegue la funzione vector_assist.apply_recommendation su ogni suggerimento.
Per eseguire la funzione, devi specificare spec_id o table_name.
Funzione
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;
Parametri
| Parametro | Obbligatorio? | Descrizione |
|---|---|---|
spec_id |
Facoltativo | Applica tutti i suggerimenti per il vettore spec_id specificato.
|
table_name |
Facoltativo | Applica tutti i suggerimenti per la tabella specificata. |
schema_name |
Facoltativo | Lo schema contenente la tabella specificata. |
column_name |
Facoltativo | Identifica text_column_name o vector_column_name da utilizzare se la tabella contiene più specifiche vettoriali. |
Valore restituito
Restituisce un valore booleano che conferma se tutti i suggerimenti sono stati applicati correttamente
e imposta il valore nella colonna della tabella vector_assist.RECOMMENDATIONS
applied su TRUE per tutti i suggerimenti.
Se l'assistente vettoriale non è in grado di applicare il suggerimento, genera un messaggio di errore.
vector_assist.modify_recommendation
Modifica la query per un suggerimento specifico e imposta il campo modified nella tabella vector_assist.RECOMMENDATIONS per il suggerimento associato su TRUE.
Funzione
CREATE OR REPLACE FUNCTION vector_assist.modify_recommendation(
recommendation_id TEXT,
modified_query TEXT
)
RETURNS BOOLEAN;
Parametri
| Parametro | Obbligatorio? | Descrizione |
|---|---|---|
recommendation_id |
Obbligatorio? | L'ID del suggerimento da modificare. |
modified_query |
Obbligatorio? | Una query SQL modificata dall'utente per il suggerimento. |
Valore restituito
Restituisce un valore booleano che conferma se un suggerimento è stato aggiornato correttamente
e imposta la colonna modified della tabella vector_assist.RECOMMENDATIONS su
TRUE.
Se l'assistente vettoriale non riesce ad aggiornare il suggerimento, genera un messaggio di errore.
vector_assist.generate_query
Genera una query di Vector Search ottimizzata in base alla specifica vettoriale e ai parametri di ricerca definiti. Questa funzione potrebbe ottimizzare il valore ef_search per soddisfare il valore target_recall impostato, se applicabile.
Funzione
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
Parametri
| Parametro | Obbligatorio? | Descrizione |
|---|---|---|
spec_id |
Facoltativo | Specifica il spec_id per cui generare la query. |
table_name |
Facoltativo | Specifica il nome della tabella per cui generare la query di ricerca se non viene fornito spec_id. Se una tabella contiene più specifiche, il parametro restituisce un errore. |
column_name |
Facoltativo | Specifica il nome della colonna per cui generare la query di ricerca se spec_id non viene fornito. Se la colonna contiene più specifiche, il parametro restituisce un errore. column_name potrebbe essere
text_column_name o vector_column_name. |
output_column_name |
Facoltativo | I nomi delle colonne da recuperare nella query di output. Per recuperare tutte le colonne, imposta questo parametro su NULL. |
search_text |
Facoltativo | Il testo di ricerca per cui generare gli embedding. Richiede embedding_model nella specifica vettoriale. L'embedding viene generato utilizzando il modello della specifica. Puoi impostare solo il parametro search_text o search_vector. |
search_vector |
Facoltativo | Il vettore per la query di ricerca. Puoi impostare solo il parametro search_text o il parametro search_vector |
top_k |
Facoltativo | Il numero di vicini più prossimi da restituire. |
filter_expressions |
Facoltativo | Le espressioni di filtro da applicare alla query di ricerca. I filtri possono essere applicati ai campi della tabella, ad esempio price < 100. |
iterative_index_search |
Facoltativo | Imposta se eseguire la ricerca iterativa nell'indice per le query filtrate.Questo parametro sostituisce le impostazioni nella specifica vettoriale. |
target_recall |
Facoltativo | Il richiamo target solo per la query di ricerca. Questo parametro
esegue l'override delle impostazioni nella specifica vettoriale e ottimizza
ef_search. |
Valore restituito
Restituisce un testo contenente la query di ricerca vettoriale per i parametri specificati. Questa query può essere eseguita o salvata per essere eseguita in un secondo momento.
vector_assist.evaluate_query_recall
Valuta il recall dell'indice vettoriale per una determinata query. Questa funzione utilizza come input le configurazioni del database e dell'indice in una stringa JSON.
Funzione
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
Parametri
| Parametro | Obbligatorio? | Descrizione |
|---|---|---|
ann_query |
Obbligatorio? | La query SQL per la quale deve essere valutato il recall. Questa query deve essere una query ANN pgvector. |
vector_search_configurations |
Facoltativo | Le configurazioni che possono essere impostate per la query ANN. Questo parametro deve essere in formato JSON. |
Valore restituito
Restituisce una tabella che valuta il recall dell'indice vettoriale per la query specificata.
La tabella contiene le seguenti colonne:
| Nome colonna | Tipo | Descrizione |
|---|---|---|
recall |
Numero in virgola mobile | La percentuale di vettori restituiti dall'indice che sono i veri vicini più prossimi. Questa metrica viene utilizzata per quantificare la qualità della ricerca. Questa funzione consente di ottimizzare i parametri per restituire i risultati di richiamo della query vettoriale previsti. |
ann_execution_time |
Numero in virgola mobile | Il tempo necessario per l'esecuzione di una query vettoriale utilizzando le scansioni dell'indice. |
ground_truth_execution_time |
Numero in virgola mobile | Il tempo necessario per eseguire la query utilizzando una scansione sequenziale. |
Esempio
L'esempio seguente valuta il recall per un indice HNSW e sostituisce il parametro di configurazione 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}'
);