VECTOR_SEARCH - MaxCompute - Alibaba Cloud Documentation Center

Fungsi VECTOR_SEARCH melakukan pencarian kemiripan vektor dan mendukung pencarian tetangga terdekat skala besar secara aproksimasi.

Batasan

Tabel input harus berupa Delta Table.
Sebelum menjalankan fungsi VECTOR_SEARCH, buat indeks vektor pada kolom vektor untuk mempercepat kueri kemiripan pada data vektor skala besar. Untuk informasi selengkapnya, lihat VECTOR INDEX. Jika tidak tersedia indeks vektor saat kueri dijalankan, sistem secara otomatis beralih ke pencarian brute-force, yang dapat menyebabkan kueri menjadi lambat.

Sintaksis

VECTOR_SEARCH(
  { TABLE base_table | (base_table_query) },      -- Tabel yang berisi vektor penyematan untuk dicari.
  column_to_search,                               -- Nama kolom di tabel dasar yang berisi vektor penyematan.
  { TABLE query_table | (query_table_query) },    -- Tabel yang menyediakan vektor penyematan kueri.
  query_column_to_search,                          -- Nama kolom di tabel kueri yang berisi vektor penyematan kueri.
  top_k                                       -- Jumlah tetangga terdekat yang akan dikembalikan.
  [, distance_type]                               -- Metrik jarak yang digunakan.
  [, options]                                     -- String JSON untuk parameter konfigurasi lainnya.
)

Parameter

Parameter	Deskripsi	Catatan
base_table \| (base_table_query)	Wajib. Tabel yang berisi vektor penyematan untuk dicari.	Input `base_table_query` dan `query_table_query` hanya mendukung rencana eksekusi simple yang terdiri dari operator `TABLE SCAN`, `FILTER`, `SELECT`, dan `TABLE ALIAS`. Input kompleks yang menghasilkan rencana eksekusi kompleks seperti `JOIN`, `GROUP BY`/`AGGREGATE`, `UNION`, `WINDOW`, atau `ORDER BY`/`LIMIT` tidak didukung. Untuk detailnya, lihat contoh Rencana input kompleks tidak didukung untuk tabel dasar atau tabel kueri. Input `base_table_query` dan `query_table_query` mendukung alias eksplisit. Jika Anda tidak menentukan alias, sistem secara otomatis menghasilkan kualifikasi default: `_base` untuk tabel dasar dan `_query` untuk tabel kueri. Untuk detailnya, lihat contoh Gunakan nama kolom berkualifikasi untuk mengakses hasil.
query_table \| (query_table_query)	Wajib. Tabel yang menyediakan vektor penyematan kueri.
column_to_search	Wajib. Kolom di tabel dasar yang berisi vektor penyematan.
query_column_to_search	Wajib. Kolom di tabel kueri yang berisi vektor penyematan kueri.
top_k	Wajib. Jumlah tetangga terdekat yang akan dikembalikan. Harus berupa bilangan bulat positif (>= 1).
distance_type	Opsi. Metrik untuk menghitung jarak antara dua vektor. Semua metrik yang didukung mengembalikan nilai jarak, di mana nilai yang lebih kecil menunjukkan kemiripan yang lebih tinggi. ● `euclidean` (default): Jarak Euclidean, yang merepresentasikan jarak garis lurus antara dua vektor dalam ruang. ● `cosine`: jarak cosine, yang mengukur perbedaan arah antara dua vektor. Sering digunakan untuk text embedding dan vektor fitur gambar. ● `dot_product`: jarak dot product, cocok untuk vektor yang telah dinormalisasi. Jangan membungkus nilai parameter `distance_type` dengan tanda kutip tunggal. Misalnya, gunakan `cosine`, bukan `'cosine'`.
options	Opsi. String berformat JSON untuk mengatur parameter konfigurasi lainnya. Parameter berikut didukung: `use_brute_force`: Nilai boolean JSON yang menentukan apakah akan menggunakan pencarian brute-force, yang melewati indeks vektor yang tersedia. Nilai default adalah `false`. '{"use_brute_force":true}' untuk menggunakan pencarian brute-force. Jika Anda mengatur parameter ini ke `false` tetapi tidak tersedia indeks vektor, sistem secara otomatis beralih ke pencarian brute-force.

Nilai kembalian

Untuk setiap baris di tabel kueri, VECTOR_SEARCH mengembalikan baris tetangga terdekat dari tabel dasar. Parameter top_k menentukan jumlah baris hasil yang dikembalikan untuk setiap baris kueri. Hasil terdiri dari tiga bagian berikut:

Kolom output tabel kueri: Semua kolom dari tabel kueri atau kolom yang dipilih dalam subkueri.
Kolom output tabel dasar: Semua kolom dari tabel dasar atau kolom yang dipilih dalam subkueri.
distance: Nilai DOUBLE yang merepresentasikan jarak antara baris tabel dasar dan tabel kueri yang bersesuaian.

Jika tabel dasar dan tabel kueri memiliki nama kolom yang sama, gunakan nama kolom berkualifikasi untuk mengakses hasilnya. Untuk detailnya, lihat contoh Gunakan nama kolom berkualifikasi untuk mengakses hasil.

Contoh

Persiapan data

-- Aktifkan tipe data VECTOR.
SET odps.sql.type.system.odps2=true;
SET odps.sql.type.vector.enable=true;

-- Tabel Dasar: Tabel vektor hewan.
CREATE TABLE IF NOT EXISTS animals (
  name      STRING,
  category  STRING,
  vec       VECTOR(FLOAT, 2)
  )
  TBLPROPERTIES (
  "table.format.version"="2"
  );

INSERT INTO animals VALUES
  ('dog',   'mammal', CAST(array(1.0, 2.0)   AS VECTOR(FLOAT, 2))),
  ('wolf',  'mammal', CAST(array(2.0, 4.0)   AS VECTOR(FLOAT, 2))),
  ('cat',   'mammal', CAST(array(1.0, 1.8)   AS VECTOR(FLOAT, 2))),
  ('lion',  'mammal', CAST(array(2.0, -2.5)  AS VECTOR(FLOAT, 2))),
  ('tiger', 'mammal', CAST(array(3.0, -2.0)  AS VECTOR(FLOAT, 2))),
  ('otter', 'mammal', CAST(array(-3.0, -1.0) AS VECTOR(FLOAT, 2))),
  ('whale', 'mammal', CAST(array(-5.0, -1.0) AS VECTOR(FLOAT, 2))),
  ('snake', 'reptile', CAST(array(-2.0, 3.0) AS VECTOR(FLOAT, 2))),
  ('lizard','reptile', CAST(array(-1.8, 2.8) AS VECTOR(FLOAT, 2))),
  ('eagle', 'bird',    CAST(array(5.0, -3.0) AS VECTOR(FLOAT, 2)));

-- Tabel Kueri: Tabel vektor hewan untuk kueri.
CREATE TABLE IF NOT EXISTS query_animals (
  query_name  STRING,
  tag       STRING,
  qvec      VECTOR(FLOAT, 2)
  )
  TBLPROPERTIES (
  "table.format.version"="2"
  );

INSERT INTO query_animals VALUES
  ('dog-like',  'mammal',  CAST(array(1.0, 2.0)  AS VECTOR(FLOAT, 2))),
  ('cat-like',  'mammal',  CAST(array(1.0, -1.0) AS VECTOR(FLOAT, 2))),
  ('snake-like','reptile', CAST(array(-2.0, 3.0) AS VECTOR(FLOAT, 2)));

Untuk kesederhanaan, contoh dalam topik ini menggunakan pencarian brute-force. Di lingkungan produksi, sebaiknya Anda membuat dan membangun indeks vektor pada kolom vektor sebelum melakukan pencarian vektor guna memastikan performa optimal. Untuk informasi selengkapnya, lihat VECTOR INDEX. Jika tidak tersedia indeks vektor, sistem secara otomatis beralih ke pencarian brute-force, yang dapat berjalan lambat.

Pencarian tabel ke tabel

Cari kolom vec pada tabel animals untuk menemukan dua vektor paling mirip untuk setiap baris di kolom qvec pada tabel query_animals.

SELECT _base.name, _query.query_name, distance
FROM VECTOR_SEARCH(
  TABLE animals, vec,
  TABLE query_animals, qvec,
  2, EUCLIDEAN
);

-- Result:
+--------+------------+---------------------+
| name   | query_name | distance            |
+--------+------------+---------------------+
| dog    | dog-like   | 0.0                 |
| cat    | dog-like   | 0.04000001773238182 |
| lion   | cat-like   | 3.25                |
| tiger  | cat-like   | 5.0                 |
| snake  | snake-like | 0.0                 |
| lizard | snake-like | 0.08000003546476364 |
+--------+------------+---------------------+

Filter sederhana pada tabel dasar

SELECT _base.name, _query.query_name, distance
FROM VECTOR_SEARCH(
  (SELECT name, vec FROM animals WHERE category = 'mammal'), vec,
  TABLE query_animals, qvec,
  2, EUCLIDEAN
);

-- Result:
+------+------------+------------+
| name | query_name | distance   |
+------+------------+------------+
| dog  | dog-like   | 5.0        |
| wolf | dog-like   | 5.0        |
| dog  | cat-like   | 2.0        |
| wolf | cat-like   | 2.0        |
| dog  | snake-like | 13.0       |
| wolf | snake-like | 13.0       |
+------+------------+------------+

Subkueri sederhana untuk tabel dasar dan tabel kueri

SELECT *
FROM VECTOR_SEARCH(
  (SELECT name, vec FROM animals WHERE category IN ('mammal', 'reptile')), vec,
  (SELECT query_name, qvec FROM query_animals WHERE tag = 'mammal'), qvec,
  2, EUCLIDEAN
);

-- Result:
+------------+---------+------+--------+------------+
| query_name | qvec    | name | vec    | distance   |
+------------+---------+------+--------+------------+
| dog-like   | [1, 2]  | dog  | [1, 2] | 5.0        |
| cat-like   | [1, -1] | dog  | [1, 2] | 2.0        |
| dog-like   | [1, 2]  | wolf | [2, 4] | 5.0        |
| cat-like   | [1, -1] | wolf | [2, 4] | 2.0        |
+------------+---------+------+--------+------------+

Pencarian dengan literal vektor tunggal

SELECT _base.name, distance
FROM VECTOR_SEARCH(
  TABLE animals, vec,
  vector(1.0f, 2.0f) AS qt(qvec),
  qvec,
  3, COSINE
);

-- Result:
+------+-----------------------+
| name | distance              |
+------+-----------------------+
| dog  | 5.960464477539063e-8  |
| wolf | 5.960464477539063e-8  |
| cat  | 0.0009437799453735352 |
+------+-----------------------+

Gunakan nama kolom berkualifikasi untuk mengakses hasil

Jika Anda tidak secara eksplisit menentukan alias untuk tabel dasar dan tabel kueri, sistem secara otomatis menghasilkan kualifikasi default: _base untuk tabel dasar dan _query untuk tabel kueri. Gunakan nama kolom berkualifikasi, seperti _base.id dan _query.id, untuk mengakses hasilnya. Mengacu pada nama kolom yang ada di kedua tabel tanpa kualifikasi bersifat ambigu dan akan menghasilkan error.

-- Tidak disarankan: Jika kedua tabel memiliki kolom 'name', kueri ini menyebabkan error ambiguitas.
SELECT name
FROM VECTOR_SEARCH(TABLE animals, vec, TABLE animals, vec, 10, COSINE);

-- Error:
FAILED: ODPS-0130071:[1,8] Semantic analysis exception - name is ambiguous, can be both _query.name or _base.name

-- Disarankan: Gunakan kualifikasi default.
SELECT _base.name, _query.query_name, distance
FROM VECTOR_SEARCH(
  TABLE animals, vec,
  TABLE query_animals, qvec,
  2, COSINE
);
-- Result:
+--------+------------+------------------------+
| name   | query_name | distance               |
+--------+------------+------------------------+
| dog    | dog-like   | 5.960464477539063e-8   |
| wolf   | dog-like   | 5.960464477539063e-8   |
| lion   | cat-like   | 0.006116271018981934   |
| tiger  | cat-like   | 0.019419312477111816   |
| snake  | snake-like | -1.1920928955078125e-7 |
| lizard | snake-like | 0.00013881921768188477 |
+--------+------------+------------------------+

-- Anda juga dapat secara eksplisit menentukan alias.
SELECT b.name, q.query_name, distance
FROM VECTOR_SEARCH(
  TABLE animals AS b, vec,
  TABLE query_animals AS q, qvec,
  2, COSINE
);
-- Result:
+--------+------------+------------------------+
| name   | query_name | distance               |
+--------+------------+------------------------+
| dog    | dog-like   | 5.960464477539063e-8   |
| wolf   | dog-like   | 5.960464477539063e-8   |
| lion   | cat-like   | 0.006116271018981934   |
| tiger  | cat-like   | 0.019419312477111816   |
| snake  | snake-like | -1.1920928955078125e-7 |
| lizard | snake-like | 0.00013881921768188477 |
+--------+------------+------------------------+

Skenario yang tidak didukung

Tabel dasar tidak mendukung sintaksis Time Travel

SELECT *
FROM VECTOR_SEARCH(
  (SELECT name, vec FROM animals VERSION AS OF 1), vec,
  TABLE query_animals, qvec,
  10, COSINE
);

-- Error:
FAILED: ODPS-0130071:[3,4] Semantic analysis exception - VECTOR_SEARCH base table does not support time travel

Rencana input kompleks tidak didukung untuk tabel dasar dan tabel kueri

Input tabel dasar dan tabel kueri tidak boleh mengandung operator kompleks seperti JOIN atau AGGREGATE.

SELECT *
FROM VECTOR_SEARCH(
  (SELECT a.name, a.vec FROM animals a JOIN query_animals b ON a.name = b.query_name), vec,
  TABLE query_animals, qvec,
  10, COSINE
);

-- Error:
FAILED: ODPS-0130071:[] Semantic analysis exception - VECTOR_SEARCH input must be a simple plan containing only SELECT, FILTER, and TABLE SCAN operators

Tabel input harus berupa Delta Table append-only

-- Buat tabel kueri yang merupakan tabel biasa, bukan Delta Table.
CREATE Table query_table_animal AS
SELECT query_name, qvec FROM query_animals;

SELECT *
FROM VECTOR_SEARCH(
  TABLE animals, vec,
  TABLE query_table_animal, qvec,
  10, COSINE
);

-- Error:
FAILED: ODPS-0130071:[] Semantic analysis exception - VECTOR_SEARCH input table must be an append delta table

VALUES multi-baris tidak didukung untuk tabel kueri

Sisi kueri mendukung VALUES dengan 0 atau 1 baris, tetapi tidak mendukung VALUES dengan beberapa baris.

SELECT *
FROM VECTOR_SEARCH(
  TABLE animals, vec,
  (
    SELECT query_name, qvec
    FROM VALUES
    ('q1', vector(1.0f, 2.0f)),
    ('q2', vector(4.0f, 5.0f)) AS q(query_name, qvec)
  ),
  qvec,
  10, COSINE
);

-- Error:
FAILED: ODPS-0130071:[] Semantic analysis exception - VECTOR_SEARCH input table must be an append delta table