Referensi bantuan vektor

Halaman ini memberikan informasi mendetail tentang semua fungsi bantuan vektor yang tersedia, serta parameter wajib dan opsionalnya.

vector_assist.define_spec

Menentukan spesifikasi vektor baru, atau spesifikasi vektor, dan menampilkan rekomendasi yang diperlukan untuk meningkatkan workload vektor. Fungsi ini menerapkan spesifikasi yang disediakan pengguna untuk membuat rekomendasi.

Fungsi

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;

Parameter

Parameter Wajib? Deskripsi
spec_id Wajib (Dibuat otomatis) ID unik untuk spesifikasi vektor yang Anda tentukan.
table_name Wajib? Nama tabel yang akan digunakan dalam penyiapan beban kerja vektor.
schema_name Opsional Skema yang berisi tabel yang akan digunakan dalam workload vektor. Skema disimpulkan secara otomatis berdasarkan jalur penelusuran skema.
vector_column_name Opsional atau wajib Nama kolom untuk kolom yang berisi penyematan vektor.

Kolom ini wajib diisi jika Anda menggunakan lebih dari satu kolom vektor dan text_column_name tidak dideklarasikan. Jika Anda hanya menggunakan satu kolom vektor, parameter ini bersifat opsional.
text_column_name Opsional atau wajib Nama kolom untuk kolom teks. Jika workload vektor Anda memerlukan pembuatan embedding dari kolom teks, parameter ini diperlukan.

Kolom ini wajib diisi jika parameter vector_column_name adalah NULL dan tidak ada kolom vektor lainnya.

Parameter ini menggunakan ekstensi google_ml_integration untuk membuat embedding dari kolom teks yang diberikan.
vector_index_type Opsional Jenis indeks vektor. Nilai yang dapat diterima mencakup:
  • HNSW
  • IVFFlat
  • SCANN
embeddings_available Opsional Boolean yang memeriksa apakah embedding vektor ada dalam tabel yang dipilih. Kolom ini ditetapkan ke FALSE jika tidak ada kolom vektor yang terdeteksi dan parameter text_column_name ditetapkan.
embedding_model Opsional atau wajib ID model dari google_ml.models yang akan digunakan untuk membuat embedding. Kolom ini bersifat opsional, kecuali jika parameter embeddings_available adalah FALSE atau NULL.
num_vectors Opsional Jumlah vektor dalam tabel.
dismensionality Opsional Dimensi vektor yang diberikan.
distance_func Opsional Fungsi jarak yang akan digunakan untuk membandingkan vektor. Nilai yang dapat diterima mencakup cosine, ip, l2, atau l1.
quantization Opsional Kuantisasi untuk indeks vektor. Nilai yang dapat diterima mencakup none, halfvec, atau bit.
prefilter_column_names Opsional Membuat indeks untuk kolom yang ditentukan untuk prapenyaringan. Hal ini dapat membantu meningkatkan performa kueri dengan filter selektivitas tinggi pada kolom.
memory_budget_kb Opsional Memori maksimum (dalam KB) untuk pembuatan indeks.
target_recall Opsional Target perolehan untuk kueri vektor standar.
target_top_k Opsional Nilai yang cocok dengan K teratas untuk diambil untuk perhitungan recall. Nilai ini digunakan jika parameter target_recall ditentukan.
tune_vector_index Opsional Menyesuaikan indeks vektor dalam workload Anda. Jika diaktifkan, bantuan vektor akan otomatis menyesuaikan indeks vektor atau kueri penelusuran menggunakan spesifikasi vektor, dan menghitung parameter indeks dan database yang optimal. Nilai yang dapat diterima mencakup TRUE atau FALSE.

Nilai yang ditampilkan

Menampilkan tabel rekomendasi yang harus diterapkan untuk menyiapkan workload vektor yang diminta. Setiap baris adalah satu rekomendasi yang berisi kueri SQL yang dapat dieksekusi dan penjelasan mendetail tentang alasan penerapan rekomendasi. Rekomendasi dapat diterapkan menggunakan fungsi apply_recommendation().

Tabel rekomendasi berisi kolom berikut:

Nama kolom Jenis Deskripsi
recommendation_id Teks ID rekomendasi. Rekomendasi diterapkan menggunakan ID ini.
vector_spec_id Teks ID spesifikasi vektor yang terkait dengan rekomendasi.
table_name Teks Nama tabel yang terkait dengan rekomendasi.
schema_name Teks Nama skema yang berisi tabel tertentu.
query Teks Kueri SQL yang dapat dieksekusi untuk mencapai hasil rekomendasi.
recommendation Teks Penjelasan untuk rekomendasi, termasuk perkiraan hasil setelah rekomendasi diterapkan. Kolom ini juga berisi alasan dan rasionalisasi rekomendasi. Anda dapat menggunakan konteks ini untuk menyesuaikan kueri sesuai kebutuhan dan membuat ulang rekomendasi.
applied Boolean Menunjukkan apakah rekomendasi telah diterapkan.
modified Boolean Menunjukkan apakah rekomendasi telah diubah oleh pengguna.
created_at Stempel waktu dengan zona waktu Waktu saat rekomendasi dibuat dalam format timestamp with time zone. Misalnya, 2024-07-18 09:00:00-08.

vector_assist.list_specs

Menampilkan spesifikasi vektor saat ini untuk tabel dan kolom tertentu.

Fungsi

CREATE OR REPLACE FUNCTION vector_assist.list_specs(
  table_name      TEXT,
  column_name     TEXT DEFAULT NULL
)
RETURNS SETOF vector_assist.VECTOR_SPECS

Parameter

Parameter Wajib? Deskripsi
table_name Wajib? Nama tabel yang spesifikasi vektornya diambil.
column_name Opsional Nama kolom untuk memfilter tabel sebelum menampilkan spesifikasi. Jika nama kolom ditentukan, spesifikasi yang berisi nama kolom teks atau vektor yang cocok dengan nama kolom ini akan ditampilkan.

Nilai yang ditampilkan

Menampilkan tabel spesifikasi untuk tabel tertentu dan secara opsional, nama kolom.

vector_assist.modify_spec

Mengubah spesifikasi vektor yang ada. Saat spesifikasi vektor diubah, rekomendasi terkait akan dibuat ulang berdasarkan spesifikasi baru.

Fungsi

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

Parameter

Parameter Wajib? Deskripsi
spec_id Wajib (Dibuat otomatis) ID unik untuk spesifikasi vektor yang Anda tentukan.
table_name Wajib? Nama tabel yang akan digunakan dalam penyiapan beban kerja vektor.
schema_name Opsional Skema yang berisi tabel yang akan digunakan dalam workload vektor. Skema disimpulkan secara otomatis berdasarkan jalur penelusuran skema.
vector_column_name Opsional atau wajib Nama kolom untuk kolom yang berisi penyematan vektor.

Kolom ini wajib diisi jika Anda menggunakan lebih dari satu kolom vektor dan text_column_name tidak dideklarasikan. Jika Anda hanya menggunakan satu kolom vektor, parameter ini bersifat opsional.
text_column_name Opsional atau wajib Nama kolom untuk kolom teks. Jika workload vektor Anda memerlukan pembuatan embedding dari kolom teks, parameter ini diperlukan.

Kolom ini wajib diisi jika parameter vector_column_name adalah NULL dan tidak ada kolom vektor lainnya.

Parameter ini menggunakan ekstensi google_ml_integration untuk membuat embedding dari kolom teks yang diberikan.
vector_index_type Opsional Jenis indeks vektor. Nilai yang dapat diterima mencakup:
  • HNSW
  • IVFFlat
  • SCANN
embeddings_available Opsional Boolean yang memeriksa apakah embedding vektor ada dalam tabel yang dipilih. Kolom ini ditetapkan ke FALSE jika tidak ada kolom vektor yang terdeteksi dan parameter text_column_name ditetapkan.
embedding_model Opsional atau wajib ID model dari google_ml.models yang akan digunakan untuk membuat embedding. Kolom ini bersifat opsional, kecuali jika parameter embeddings_available adalah FALSE atau NULL.
num_vectors Opsional Jumlah vektor dalam tabel.
dismensionality Opsional Dimensi vektor yang diberikan.
distance_func Opsional Fungsi jarak yang akan digunakan untuk membandingkan vektor. Nilai yang dapat diterima mencakup cosine, ip, l2, atau l1.
quantization Opsional Kuantisasi untuk indeks vektor. Nilai yang dapat diterima mencakup none, halfvec, atau bit.
prefilter_column_names Opsional Mengidentifikasi kolom yang tersedia untuk prapenyaringan dalam kueri penelusuran vektor.
memory_budget_kb Opsional Memori maksimum (dalam KB) untuk pembuatan indeks.
target_recall Opsional Target perolehan untuk kueri vektor standar.
target_top_k Opsional Nilai yang cocok dengan K teratas untuk diambil untuk perhitungan recall. Nilai ini digunakan jika parameter target_recall ditentukan.
tune_vector_index Opsional Menyesuaikan indeks vektor dalam workload Anda. Jika diaktifkan, bantuan vektor akan otomatis menyesuaikan indeks vektor atau kueri penelusuran menggunakan spesifikasi vektor, dan menghitung parameter indeks dan database yang optimal. Nilai yang dapat diterima mencakup TRUE atau FALSE.

Nilai yang ditampilkan

Menampilkan tabel rekomendasi yang diperbarui yang harus diterapkan untuk menyiapkan workload vektor yang diminta. Setiap baris adalah satu rekomendasi yang berisi kueri SQL yang dapat dieksekusi dan penjelasan mendetail tentang alasan penerapan rekomendasi. Rekomendasi dapat diterapkan menggunakan fungsi apply_recommendation().

Tabel rekomendasi berisi kolom berikut:

Nama kolom Jenis Deskripsi
recommendation_id Teks ID rekomendasi. Rekomendasi diterapkan menggunakan ID ini.
vector_spec_id Teks ID spesifikasi vektor yang terkait dengan rekomendasi.
table_name Teks Nama tabel yang terkait dengan rekomendasi.
schema_name Teks Nama skema yang berisi tabel tertentu.
query Teks Kueri SQL yang dapat dieksekusi untuk mencapai hasil rekomendasi.
recommendation Teks Penjelasan untuk rekomendasi, termasuk perkiraan hasil setelah rekomendasi diterapkan. Kolom ini juga berisi alasan dan rasionalisasi rekomendasi. Anda dapat menggunakan konteks ini untuk menyesuaikan kueri sesuai kebutuhan dan membuat ulang rekomendasi.
applied Boolean Menunjukkan apakah rekomendasi telah diterapkan.
modified Boolean Menunjukkan apakah rekomendasi telah diubah oleh pengguna.
created_at Stempel waktu dengan zona waktu Waktu saat rekomendasi dibuat.

vector_assist.get_recommendations

Menampilkan rekomendasi yang terkait dengan vektor spec_id tertentu.

Fungsi

CREATE OR REPLACE FUNCTION vector_assist.get_recommendations (
    spec_id TEXT
)
RETURNS SETOF vector_assist.RECOMMENDATIONS;

Parameter

Parameter Wajib? Deskripsi
spec_id Wajib? Mendapatkan rekomendasi untuk vektor spec_id yang ditentukan.

Nilai yang ditampilkan

Menampilkan tabel rekomendasi yang diminta.

Tabel rekomendasi berisi kolom berikut:

Nama kolom Jenis Deskripsi
recommendation_id Teks ID rekomendasi. Rekomendasi diterapkan menggunakan ID ini.
vector_spec_id Teks ID spesifikasi vektor yang terkait dengan rekomendasi.
table_name Teks Nama tabel yang terkait dengan rekomendasi.
schema_name Teks Nama skema yang berisi tabel tertentu.
query Teks Kueri SQL yang dapat dieksekusi untuk mencapai hasil rekomendasi.
recommendation Teks Penjelasan untuk rekomendasi, termasuk perkiraan hasil setelah rekomendasi diterapkan. Kolom ini juga berisi alasan dan rasionalisasi rekomendasi. Anda dapat menggunakan konteks ini untuk menyesuaikan kueri sesuai kebutuhan dan membuat ulang rekomendasi.
applied Boolean Menunjukkan apakah rekomendasi telah diterapkan.
modified Boolean Menunjukkan apakah rekomendasi telah diubah oleh pengguna.
created_at Stempel waktu dengan zona waktu Waktu saat rekomendasi dibuat.

vector_assist.apply_recommendation

Menerapkan satu rekomendasi menggunakan recommendation_id.

Fungsi

CREATE OR REPLACE FUNCTION vector_assist.get_recommendations (
    spec_id TEXT
)
RETURNS SETOF vector_assist.RECOMMENDATIONS;

Parameter

Parameter Wajib? Deskripsi
recommenation_id Wajib? ID rekomendasi vektor yang akan diterapkan.

Nilai yang ditampilkan

Menampilkan boolean yang mengonfirmasi apakah rekomendasi berhasil diterapkan dan memperbarui kolom tabel vector_assist.RECOMMENDATIONS applied menjadi TRUE.

Jika bantuan vektor tidak dapat menerapkan rekomendasi, pesan error akan muncul jika terjadi kegagalan.

vector_assist.apply_spec

Menerapkan semua rekomendasi yang terkait dengan vektor spec_id atau nama tabel tertentu. Fungsi ini akan memeriksa semua rekomendasi dan menjalankan fungsi vector_assist.apply_recommendation pada setiap rekomendasi.

Harus menentukan spec_id atau table_name untuk menjalankan fungsi.

Fungsi

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;

Parameter

Parameter Wajib? Deskripsi
spec_id Opsional Menerapkan semua rekomendasi untuk vektor spec_id tertentu.
table_name Opsional Menerapkan semua rekomendasi untuk tabel tertentu.
schema_name Opsional Skema yang berisi tabel yang ditentukan.
column_name Opsional Mengidentifikasi text_column_name atau vector_column_name yang akan digunakan jika tabel berisi beberapa spesifikasi vektor.

Nilai yang ditampilkan

Menampilkan boolean yang mengonfirmasi apakah semua rekomendasi berhasil diterapkan dan menetapkan nilai di kolom tabel vector_assist.RECOMMENDATIONS applied ke TRUE untuk semua rekomendasi.

Jika bantuan vektor tidak dapat menerapkan rekomendasi, pesan error akan muncul jika terjadi kegagalan.

vector_assist.modify_recommendation

Mengubah kueri untuk rekomendasi tertentu dan menetapkan kolom modified dalam tabel vector_assist.RECOMMENDATIONS untuk rekomendasi terkait ke TRUE.

Fungsi

CREATE OR REPLACE FUNCTION vector_assist.modify_recommendation(
    recommendation_id TEXT,
    modified_query TEXT
)
RETURNS BOOLEAN;

Parameter

Parameter Wajib? Deskripsi
recommendation_id Wajib? ID rekomendasi yang akan diubah.
modified_query Wajib? Kueri SQL yang diubah pengguna untuk rekomendasi.

Nilai yang ditampilkan

Menampilkan boolean yang mengonfirmasi apakah rekomendasi berhasil diperbarui dan menetapkan kolom tabel vector_assist.RECOMMENDATIONS modified ke TRUE.

Jika bantuan vektor tidak dapat memperbarui rekomendasi, pesan error akan muncul jika terjadi kegagalan.

vector_assist.generate_query

Membuat kueri penelusuran vektor yang dioptimalkan berdasarkan spesifikasi vektor dan parameter penelusuran yang ditentukan. Fungsi ini dapat menyesuaikan nilai ef_search untuk memenuhi target_recall yang ditetapkan jika berlaku.

Fungsi

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

Parameter

Parameter Wajib? Deskripsi
spec_id Opsional Menentukan spec_id untuk membuat kueri.
table_name Opsional Menentukan nama tabel untuk membuat kueri penelusuran jika spec_id tidak diberikan. Jika tabel berisi beberapa spesifikasi, parameter akan menampilkan error.
column_name Opsional Menentukan nama kolom untuk membuat kueri penelusuran jika spec_id tidak diberikan. Jika kolom berisi beberapa spesifikasi, maka parameter akan menampilkan error. column_name mungkin berupa text_column_name atau vector_column_name.
output_column_name Opsional Nama kolom yang akan diambil dalam kueri output. Untuk mengambil semua kolom, tetapkan parameter ini ke NULL.
search_text Opsional Teks penelusuran untuk membuat embedding. Memerlukan embedding_model dalam spesifikasi vektor. Embedding dibuat menggunakan model dari spesifikasi. Anda hanya dapat menyetel parameter search_text atau search_vector.
search_vector Opsional Vektor untuk kueri penelusuran. Anda hanya dapat menetapkan parameter search_text atau search_vector
top_k Opsional Jumlah tetangga terdekat yang akan ditampilkan.
filter_expressions Opsional Ekspresi filter yang akan diterapkan dalam kueri penelusuran. Filter dapat diterapkan ke kolom dalam tabel, seperti harga < 100.
iterative_index_search Opsional Menetapkan apakah akan melakukan penelusuran indeks iteratif untuk kueri yang difilter.Parameter ini menggantikan setelan dalam spesifikasi vektor.
target_recall Opsional Target perolehan untuk kueri penelusuran saja. Parameter ini menggantikan setelan dalam spesifikasi vektor dan menyesuaikan ef_search.

Nilai yang ditampilkan

Menampilkan teks yang berisi kueri penelusuran vektor untuk parameter tertentu. Kueri ini dapat dieksekusi atau disimpan untuk dijalankan nanti.

vector_assist.evaluate_query_recall

Mengevaluasi recall indeks vektor untuk kueri tertentu. Fungsi ini menggunakan konfigurasi database dan indeks dalam string JSON sebagai input.

Fungsi

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

Parameter

Parameter Wajib? Deskripsi
ann_query Wajib? Kueri SQL yang perlu dievaluasi perolehan kembali informasinya. Kueri ini harus berupa kueri ANN pgvector.
vector_search_configurations Opsional Konfigurasi yang dapat ditetapkan untuk kueri ANN. Parameter ini harus dalam format JSON.

Nilai yang ditampilkan

Menampilkan tabel yang mengevaluasi perolehan indeks vektor untuk kueri yang diberikan.

Tabel berisi kolom berikut:

Nama kolom Jenis Deskripsi
recall Float Persentase vektor yang ditampilkan indeks, yang merupakan tetangga terdekat sebenarnya. Metrik ini digunakan untuk mengukur kualitas penelusuran. Fungsi ini memungkinkan Anda menyesuaikan parameter untuk menampilkan hasil pencarian vektor yang diharapkan.
ann_execution_time Float Waktu yang diperlukan kueri vektor untuk dieksekusi menggunakan pemindaian indeks.
ground_truth_execution_time Float Waktu yang diperlukan kueri untuk berjalan menggunakan pemindaian berurutan.

Contoh

Contoh berikut mengevaluasi recall untuk indeks HNSW dan menggantikan parameter konfigurasi 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}'
);