VECTOR_SEARCH - MaxCompute - Centre de documentation Alibaba Cloud

La fonction VECTOR_SEARCH effectue une recherche de similarité vectorielle et prend en charge la recherche approximative du plus proche voisin (ANN) à grande échelle.

Limites

La table d'entrée doit être une Delta Table.
Avant d'exécuter la fonction VECTOR_SEARCH, créez un index vectoriel sur la colonne de vecteurs pour accélérer les requêtes de similarité sur les données vectorielles volumineuses. Pour plus d'informations, consultez la rubrique VECTOR INDEX. Si aucun index vectoriel n'est disponible au moment de la requête, le système revient automatiquement à une recherche exhaustive, ce qui peut ralentir l'exécution des requêtes.

Syntaxe

VECTOR_SEARCH(
  { TABLE base_table | (base_table_query) },      -- The table containing embedding vectors to search.
  column_to_search,                               -- The name of the column in the base table that contains the embedding vectors.
  { TABLE query_table | (query_table_query) },    -- The table that provides the query embedding vectors.
  query_column_to_search,                          -- The name of the column in the query table that contains the query embedding vectors.
  top_k                                       -- The number of nearest neighbors to return.
  [, distance_type]                               -- The distance metric to use.
  [, options]                                     -- A JSON string for other configurable parameters.
)

Paramètres

Paramètre	Description	Notes
base_table \| (base_table_query)	Obligatoire. Table contenant les vecteurs d'embedding à rechercher.	Les entrées `base_table_query` et `query_table_query` prennent uniquement en charge des plans simples composés des opérateurs `TABLE SCAN`, `FILTER`, `SELECT` et `TABLE ALIAS`. Les entrées complexes générant des plans d'exécution élaborés, tels que `JOIN`, `GROUP BY`/`AGGREGATE`, `UNION`, `WINDOW` ou `ORDER BY`/`LIMIT`, ne sont pas prises en charge. Pour plus de détails, consultez l'exemple Les plans d'entrée complexes ne sont pas pris en charge pour les tables de base ou de requête. Les entrées `base_table_query` et `query_table_query` acceptent un alias explicite. Si vous ne spécifiez pas d'alias, le système génère automatiquement des qualificateurs par défaut : `_base` pour la table de base et `_query` pour la table de requête. Pour plus de détails, consultez l'exemple Utilisez des noms de colonnes qualifiés pour accéder aux résultats.
query_table \| (query_table_query)	Obligatoire. Table fournissant les vecteurs d'embedding de requête.
column_to_search	Obligatoire. Colonne de la table de base contenant les vecteurs d'embedding.
query_column_to_search	Obligatoire. Colonne de la table de requête contenant les vecteurs d'embedding de requête.
top_k	Obligatoire. Nombre de plus proches voisins à renvoyer. Doit être un entier positif (>= 1).
distance_type	Facultatif. Métrique utilisée pour calculer la distance entre deux vecteurs. Toutes les métriques prises en charge renvoient une valeur de distance, où une valeur plus faible indique une similarité plus grande. ● `euclidean` (par défaut) : distance euclidienne, qui représente la distance en ligne droite entre deux vecteurs dans l'espace. ● `cosine` : distance cosinus, qui mesure la différence de direction entre deux vecteurs. Elle est souvent utilisée pour les embeddings de texte et les vecteurs de caractéristiques d'image. ● `dot_product` : distance basée sur le produit scalaire, adaptée aux vecteurs normalisés. N'entourez pas la valeur du paramètre `distance_type` de guillemets simples. Par exemple, spécifiez `cosine`, et non `'cosine'`.
options	Facultatif. Chaîne au format JSON permettant de définir d'autres paramètres configurables. Le paramètre suivant est pris en charge : `use_brute_force` : valeur booléenne JSON indiquant s'il faut utiliser la recherche exhaustive, qui contourne tout index vectoriel disponible. La valeur par défaut est `false`. '{"use_brute_force":true}' pour utiliser la recherche exhaustive. Si vous définissez ce paramètre sur `false` mais qu'aucun index vectoriel n'est disponible, le système revient automatiquement à une recherche exhaustive.

Valeur de retour

Pour chaque ligne de la table de requête, VECTOR_SEARCH renvoie les lignes de la table de base correspondant aux plus proches voisins. Le paramètre top_k spécifie le nombre de lignes de résultat à renvoyer pour chaque ligne de requête. Le résultat se compose des trois parties suivantes :

Colonnes de sortie de la table de requête : toutes les colonnes de la table de requête ou les colonnes sélectionnées dans une sous-requête.
Colonnes de sortie de la table de base : toutes les colonnes de la table de base ou les colonnes sélectionnées dans une sous-requête.
distance : valeur DOUBLE représentant la distance entre les lignes correspondantes des tables de base et de requête.

Si les tables de base et de requête partagent des noms de colonnes, utilisez un nom de colonne qualifié pour accéder aux résultats. Pour plus de détails, consultez l'exemple Utilisez des noms de colonnes qualifiés pour accéder aux résultats.

Exemples

Préparation des données

-- Enable the VECTOR data type.
SET odps.sql.type.system.odps2=true;
SET odps.sql.type.vector.enable=true;

-- Base Table: A table of animal vectors.
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)));

-- Query Table: A table of animal vectors to query.
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)));

Par souci de simplicité, les exemples de cette rubrique utilisent une recherche exhaustive. Dans un environnement de production, créez et construisez un index vectoriel sur la colonne de vecteurs avant d'effectuer une recherche vectorielle afin de garantir des performances optimales. Pour plus d'informations, consultez la rubrique VECTOR INDEX. Si aucun index vectoriel n'est disponible, le système revient automatiquement à une recherche exhaustive, ce qui peut être lent.

Recherche de table à table

Recherchez dans la colonne vec de la table animals pour trouver les deux vecteurs les plus similaires pour chaque ligne de la colonne qvec de la table 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 |
+--------+------------+---------------------+

Filtre simple sur la table de base

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       |
+------+------------+------------+

Sous-requêtes simples pour les tables de base et de requête

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        |
+------------+---------+------+--------+------------+

Recherche avec un littéral de vecteur unique

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 |
+------+-----------------------+

Utilisez des noms de colonnes qualifiés pour accéder aux résultats

Si vous ne spécifiez pas explicitement d'alias pour les tables de base et de requête, le système génère automatiquement des qualificateurs par défaut : _base pour la table de base et _query pour la table de requête. Utilisez des noms de colonnes qualifiés, tels que _base.id et _query.id, pour accéder aux résultats. Faire référence à un nom de colonne présent dans les deux tables sans qualificateur est ambigu et provoque une erreur.

-- Not recommended: If both tables have a 'name' column, this query causes an ambiguity error.
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

-- Recommended: Use the default qualifiers.
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 |
+--------+------------+------------------------+

-- You can also explicitly specify an 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 |
+--------+------------+------------------------+

Scénarios non pris en charge

La table de base ne prend pas en charge la syntaxe 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

Les plans d'entrée complexes ne sont pas pris en charge pour les tables de base et de requête

Les entrées des tables de base et de requête ne peuvent pas contenir d'opérateurs complexes tels que JOIN ou 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

Les tables d'entrée doivent être des Delta Tables en ajout seul

-- Create a query table that is a regular table, not a 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

Les valeurs VALUES multi-lignes ne sont pas prises en charge pour la table de requête

Le côté requête prend en charge VALUES avec 0 ou 1 ligne, mais ne prend pas en charge VALUES avec plusieurs lignes.

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