Partage via

VECTOR_SEARCH (Transact-SQL) (préversion)

S’applique à : SQL Server 2025 (17.x) Azure SQL DatabaseSQL database in Microsoft Fabric

Recherchez des vecteurs similaires à des vecteurs de requête donnés à l’aide d’un algorithme de recherche de vecteurs voisin le plus proche. Pour en savoir plus sur le fonctionnement de l’indexation vectorielle et de la recherche vectorielle et les différences entre la recherche exacte et approximative, reportez-vous à la recherche vectorielle et aux index vectoriels dans le moteur de base de données SQL.

Base de données Azure SQL et base de données SQL dans Fabric

La fonctionnalité est en aperçu. Veillez à consulter les limitations actuelles avant de l’utiliser.

Note

En tant que fonctionnalité en préversion, la technologie présentée dans cet article est soumise aux conditions d’utilisation supplémentaires des préversions de Microsoft Azure.

Important

Pour obtenir des performances optimales et accéder aux dernières fonctionnalités de recherche vectorielle, utilisez des index vectoriels créés avec la dernière version. Pour plus d’informations sur la mise à niveau des index existants et la comparaison des versions, consultez CREATE VECTOR INDEX - Mettre à niveau les index vectoriels vers la dernière version.

Disponibilité régionale

Cette fonctionnalité est déployée dans Azure SQL Database et sql Database dans Microsoft Fabric. Pendant le déploiement, la disponibilité et le comportement peuvent varier selon la région et la version d’index. Si une fonctionnalité ou une syntaxe n’est pas disponible, elle devient automatiquement disponible à mesure que le déploiement se termine. Pour connaître l’état actuel de la disponibilité régionale, consultez Disponibilité des fonctionnalités par région.

Avertissement

Avis de dépréciation : le TOP_N paramètre dans VECTOR_SEARCH est déconseillé et conservé uniquement pour la compatibilité descendante avec les index vectoriels de version antérieure. Les nouvelles implémentations doivent utiliser SELECT TOP (N) WITH APPROXIMATE la syntaxe à la place. Pour plus d’informations, consultez Syntaxe.

Fonctionnalité d’aperçu de SQL Server 2025

Dans SQL Server 2025, cette fonction est en aperçu et peut être modifiée. Pour utiliser cette fonctionnalité, vous devez activer la PREVIEW_FEATURES la base de données.

Veillez à consulter les limitations actuelles avant de l’utiliser.

Note

La dernière version des index vectoriels est disponible uniquement dans Azure SQL Database et dans la base de données SQL dans Microsoft Fabric actuellement.

Améliorations clés avec les derniers index vectoriels

Les index vectoriels créés avec la dernière version présentent des améliorations significatives :

  • Prise en charge complète de DML : supprime la limitation précédente qui a rendu les tables indexées vectorielles en lecture seule après la création de l’index. Vous pouvez maintenant effectuer des opérations INSERT, UPDATE, DELETE et MERGE tout en conservant la fonctionnalité d’index vectoriel avec la maintenance automatique et en temps réel des index
  • Filtrage itératif : les prédicats dans la clause WHERE sont appliqués pendant le processus de recherche vectorielle, et non après la récupération
  • Optimisé : l’optimiseur de requête détermine automatiquement s’il faut utiliser l’index DiskANN ou la recherche kNN en fonction des caractéristiques de requête
  • Quantisation avancée : les techniques de quantisation vectorielle ont été intégrées pour améliorer l’efficacité du stockage et accélérer les performances des requêtes, ces optimisations étant transparentes pour les utilisateurs

Syntax

Conventions de la syntaxe Transact-SQL

Avec les derniers index vectoriels de version :

Important

Lors de l’interrogation de tables qui utilisent la dernière version de l’index vectoriel, la recherche vectorielle approximative doit utiliser la syntaxe TOP (N) APPROXIMATE. Cette exigence de syntaxe indique que la requête demande explicitement des résultats approximatifs du voisin le plus proche.

SELECT TOP (N) WITH APPROXIMATE
    column_list
FROM VECTOR_SEARCH(
        TABLE = object [ AS source_table_alias ]
        , COLUMN = vector_column
        , SIMILAR_TO = query_vector
        , METRIC = { 'cosine' | 'dot' | 'euclidean' }
    ) [ AS result_table_alias ]
[ WHERE predicate ]
ORDER BY distance;

Avec les index vectoriels de version antérieure :

VECTOR_SEARCH(
    TABLE = object [ AS source_table_alias ]
    , COLUMN = vector_column
    , SIMILAR_TO = query_vector
    , METRIC = { 'cosine' | 'dot' | 'euclidean' }
    , TOP_N = k
) [ AS result_table_alias ]

Important

Le TOP_N paramètre n’est pas pris en charge avec les derniers index vectoriels de version. Utilisez la SELECT TOP (N) WITH APPROXIMATE syntaxe ci-dessus. Pour plus d’informations, consultez Erreur à l’aide de la syntaxe héritée.

Arguments

TABLE = objet [AS source_table_alias]

Table sur laquelle effectuer la recherche. Il doit s’agir d’une table de base. Les vues, les tables temporaires, locales et globales, ne sont pas prises en charge.

COLONNE = vector_column

Colonne vectorielle dans laquelle la recherche est effectuée. La colonne doit être un type de données vectorielle .

SIMILAR_TO = query_vector

Vecteur utilisé pour la recherche. Il doit s’agir d’une variable ou d’une colonne de type vectoriel .

METRIC = { 'cosin' | 'dot' | 'euclidean' }

Métrique de distance utilisée pour calculer la distance entre le vecteur de requête et les vecteurs de la colonne spécifiée. Un index ANN (Voisin le plus proche approximatif) est utilisé uniquement si un index ANN correspondant, avec la même métrique et sur la même colonne, est trouvé. S’il n’existe aucun index ANN compatible, un avertissement est déclenché et l’algorithme kNN (k-nearest voisin) est utilisé.

TOP_N = <k>

Avertissement

Ce paramètre est déconseillé et géré uniquement pour la compatibilité descendante avec les index vectoriels de version antérieure. Pour les index de version les plus récents, utilisez SELECT TOP (N) WITH APPROXIMATE plutôt la syntaxe. Les nouvelles implémentations doivent utiliser la dernière syntaxe.

Nombre maximal de vecteurs similaires qui doivent être retournés. Il doit s’agir d’un entier positif. Ce paramètre n’est pas pris en charge avec les index vectoriels créés à l’aide de la dernière version.

result_table_alias

L’alias est utilisé pour référencer le jeu de résultats.

Retourner le jeu de résultats

Le jeu de résultats retourné par la VECTOR_SEARCH fonction inclut :

  • Toutes les colonnes de la table spécifiées dans l’argument TABLE .

  • Colonne supplémentaire nommée distance, qui représente la distance entre le vecteur dans la colonne spécifiée par l’argument COLUMN et le vecteur fourni dans l’argument SIMILAR_TO .

La colonne de distance est générée par la VECTOR_SEARCH fonction elle-même, tandis que toutes les autres colonnes proviennent de la table référencée dans l’argument TABLE .

Si vous utilisez un alias pour la table dans l’argument TABLE , vous devez utiliser ce même alias pour référencer ses colonnes dans l’instruction SELECT . Vous ne pouvez pas utiliser l’alias affecté pour référencer VECTOR_SEARCH des colonnes à partir de la table spécifiée dans TABLE. Ce comportement est plus facile à comprendre si vous pensez au jeu de résultats généré en prenant la sortie et en la fusionnant avec les données de VECTOR_SEARCH table.

Si la table spécifiée dans l’argument TABLE contient déjà une colonne nommée distance, le comportement sera similaire à une jointure SQL entre deux tables qui partagent un nom de colonne. Dans ce cas, vous devez utiliser des alias de table pour lever l’ambiguïté des références de colonne ; sinon, une erreur est générée.

Important

La distance colonne est la seule clé de classement valide pour les résultats de recherche vectorielle approximative.

Limitations

  • Ordre croissant uniquement : la distance colonne doit être triée dans l’ordre croissant (ASC). L’ordre décroissant (DESC) n’est pas pris en charge.

Comportement spécifique à la version

Le comportement varie en fonction de la version de VECTOR_SEARCH l’index vectoriel.

Versions antérieures de l’index vectoriel

Note

Ces limitations s’appliquent uniquement aux index vectoriels créés avec les versions antérieures. Migrez vers la dernière version pour activer le filtrage itératif. Consultez Migration à partir des versions antérieures de l’index vectoriel.

Post-filtrage uniquement : la recherche vectorielle se produit avant d’appliquer un prédicat. Les prédicats supplémentaires sont appliqués uniquement après le retour des vecteurs les plus similaires. L’exemple suivant retourne les 10 premières lignes avec des incorporations les plus similaires au vecteur @qvde requête, puis applique le prédicat spécifié dans la WHERE clause. Si aucune des 10 lignes associées aux vecteurs retournés par la recherche vectorielle n’a la accepted colonne égale à 1, le résultat est vide.

SELECT TOP (10) s.id,
                s.title,
                r.distance
FROM VECTOR_SEARCH(
         TABLE = dbo.sessions AS s,
         COLUMN = embedding,
         SIMILAR_TO = @qv,
         METRIC = 'cosine',
         TOP_N = 10
     ) AS r
WHERE accepted = 1
ORDER BY r.distance;

Limitations générales

VECTOR_SEARCH ne peut pas être utilisé dans le corps d’une vue.

Examples

Important

Lors de l’interrogation de tables qui utilisent la dernière version de l’index vectoriel, la recherche vectorielle approximative doit utiliser la TOP (N) WITH APPROXIMATE syntaxe. Cette exigence de syntaxe indique que la requête demande explicitement des résultats approximatifs du voisin le plus proche.

L’exemple suivant recherche les 10 articles les plus similaires au Pink Floyd music stylewikipedia_articles_embeddings tableau.

DECLARE @qv VECTOR(1536) = AI_GENERATE_EMBEDDINGS(N'Pink Floyd music style' USE MODEL Ada2Embeddings);

SELECT TOP (10) WITH APPROXIMATE
    t.id,
    t.title,
    r.distance
FROM VECTOR_SEARCH(
        TABLE = dbo.wikipedia_articles_embeddings AS t,
        COLUMN = content_vector,
        SIMILAR_TO = @qv,
        METRIC = 'cosine'
    ) AS r
ORDER BY r.distance;

La syntaxe d’interrogation dépend de la version de l’index vectoriel :

Version de l’index vectoriel Exemple de syntaxe
Version la plus récente Utiliser SELECT TOP (N) WITH APPROXIMATE sans TOP_N paramètre
Versions antérieures (déconseillées) Utiliser un TOP_N paramètre dans la VECTOR_SEARCH fonction

Conseil / Astuce

Pour déterminer votre version d’index vectoriel, consultez Migration à partir des versions antérieures de l’index vectoriel.

Pour les index de version antérieures (syntaxe déconseillée) :

DECLARE @qv VECTOR(1536) = AI_GENERATE_EMBEDDINGS(N'Pink Floyd music style' USE MODEL Ada2Embeddings);

SELECT TOP (10)
    t.id,
    t.title,
    r.distance
FROM VECTOR_SEARCH(
        TABLE = dbo.wikipedia_articles_embeddings AS t,
        COLUMN = content_vector,
        SIMILAR_TO = @qv,
        METRIC = 'cosine',
        TOP_N = 10  -- Deprecated: Use SELECT TOP (N) WITH APPROXIMATE instead
    ) AS r
ORDER BY r.distance;

Note

L’utilisation du paramètre avec les TOP_N derniers index vectoriels de version retourne l’erreur Msg 42274. Pour plus d’informations, consultez Erreur à l’aide de la syntaxe héritée dans la section Comportements attendus.

B. Terminer le flux de travail avec la création d’index

Exemple de base de bout en bout utilisant CREATE VECTOR INDEX et de la fonction associée VECTOR_SEARCH . Les incorporations sont simulées. Dans un scénario réel, les incorporations sont générées à l’aide d’un modèle d’incorporation et de AI_GENERATE_EMBEDDINGS, ou d’une bibliothèque externe telle qu’OpenAI SDK.

Note

Les derniers index vectoriels de version nécessitent au moins 100 lignes de données avant la création de l’index. Cet exemple insère 100 lignes pour répondre à cette exigence. Pour plus d’informations, consultez Configuration minimale requise pour les données.

Le bloc de code suivant illustre la VECTOR_SEARCH fonction avec des incorporations fictifs :

  1. Active la fonctionnalité en préversion (obligatoire pour SQL Server 2025 uniquement ; non nécessaire pour Azure SQL Database ou sql database dans Fabric).
  2. Créez un exemple de table dbo.Articles avec une colonne embedding avec un vecteur de type de données (5).
  3. Insérez 100 lignes d’exemples de données avec des données incorporées fictifs.
  4. Créez un index vectoriel sur dbo.Articles.embedding.
  5. Illustrez la recherche de similarité vectorielle avec la VECTOR_SEARCH fonction.
-- Step 0: Enable Preview Feature (SQL Server 2025 only)
ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;
GO

-- Step 1: Create a sample table with a VECTOR(5) column
CREATE TABLE dbo.Articles
(
    id INT PRIMARY KEY,
    title NVARCHAR(100),
    content NVARCHAR(MAX),
    embedding VECTOR(5) -- mocked embeddings
);
GO

-- Step 2: Insert sample data (100 rows required for latest version indexes)
INSERT INTO Articles (id, title, content, embedding)
SELECT
    value AS id,
    'Article ' || [value],
    'Content for article ' || [value],
    CAST(JSON_ARRAY(
        CAST(value * 0.01 AS FLOAT),
        CAST(value * 0.02 AS FLOAT),
        CAST(value * 0.03 AS FLOAT),
        CAST(value * 0.04 AS FLOAT),
        CAST(value * 0.05 AS FLOAT)
    ) AS VECTOR(5))
FROM GENERATE_SERIES(1, 100);
GO

-- Step 3: Create a vector index on the embedding column
CREATE VECTOR INDEX vec_idx ON Articles(embedding)
WITH (METRIC = 'cosine', TYPE = 'diskann');
GO

-- Step 4: Perform a vector similarity search
DECLARE @qv VECTOR(5) = '[0.3, 0.3, 0.3, 0.3, 0.3]';
SELECT TOP(3) WITH APPROXIMATE
    t.id,
    t.title,
    t.content,
    s.distance
FROM
    VECTOR_SEARCH(
        TABLE = Articles AS t,
        COLUMN = embedding,
        SIMILAR_TO = @qv,
        METRIC = 'cosine'
    ) AS s
ORDER BY s.distance, t.title;

La syntaxe d’interrogation dépend de la version de l’index vectoriel :

Version de l’index vectoriel Exemple de syntaxe
Version la plus récente Utiliser SELECT TOP (N) WITH APPROXIMATE sans TOP_N paramètre
Versions antérieures (déconseillées) Utiliser un TOP_N paramètre dans la VECTOR_SEARCH fonction

Pour les index de version antérieures (syntaxe déconseillée) :

DECLARE @qv VECTOR(5) = '[0.3, 0.3, 0.3, 0.3, 0.3]';
SELECT TOP(3)
    t.id,
    t.title,
    t.content,
    s.distance
FROM
    VECTOR_SEARCH(
        TABLE = Articles AS t,
        COLUMN = embedding,
        SIMILAR_TO = @qv,
        METRIC = 'cosine',
        TOP_N = 3  -- Deprecated: Use SELECT TOP (N) WITH APPROXIMATE instead
    ) AS s
ORDER BY s.distance, t.title;

Chapitre C. Recherche vectorielle avec filtrage itératif

L’exemple suivant illustre le filtrage itératif avec les derniers index vectoriels de version. La requête recherche des articles similaires lors de l’application de prédicats pendant le processus de recherche.

Avec les derniers index de version, les prédicats de la clause WHERE sont appliqués pendant le processus de recherche vectorielle (pas après). Le moteur continue de rechercher jusqu’à ce qu’il trouve 5 lignes éligibles qui correspondent à tous les critères :

  • Similarité vectorielle aux « algorithmes d’apprentissage automatique »
  • La catégorie est égale à « Technologie »
  • L’état publié est égal à 1

Cela garantit que vous obtenez exactement 5 résultats (s’ils existent) sans régler manuellement les paramètres de recherche. Pour obtenir une comparaison détaillée entre les versions antérieures et les dernières versions, consultez le comportement de filtrage itératif dans la section Comportements attendus.

DECLARE @qv VECTOR(1536) = AI_GENERATE_EMBEDDINGS(N'machine learning algorithms' USE MODEL Ada2Embeddings);

SELECT TOP (5) WITH APPROXIMATE
    t.id,
    t.title,
    t.category,
    r.distance
FROM VECTOR_SEARCH(
        TABLE = dbo.wikipedia_articles AS t,
        COLUMN = content_vector,
        SIMILAR_TO = @qv,
        METRIC = 'cosine'
    ) AS r
WHERE t.category = 'Technology'
  AND t.published = 1
ORDER BY r.distance;

Note

Certaines opérations SQL telles que GROUP BY, les fonctions d’agrégation et les fonctions de fenêtre nécessitent un modèle de sous-requête. Pour plus d’informations, consultez La combinaison de la recherche vectorielle avec d’autres opérations SQL.

D. Jointures à plusieurs tables avec INNER JOIN

L’exemple suivant illustre inner JOIN avec filtrage sur plusieurs tables. Utilisez cette option lorsque des incorporations sont stockées dans une table distincte des données d’entité principale.

-- Assuming a schema with separate tables for articles and embeddings
DECLARE @qv VECTOR(1536) = AI_GENERATE_EMBEDDINGS(N'artificial intelligence and machine learning' USE MODEL Ada2Embeddings);

SELECT TOP (10) WITH APPROXIMATE
    a.id,
    a.title,
    a.category,
    vs.distance
FROM wikipedia_articles a
INNER JOIN VECTOR_SEARCH(
    TABLE = wikipedia_articles_embeddings AS e,
    COLUMN = content_vector,
    SIMILAR_TO = @qv,
    METRIC = 'cosine'
) AS vs ON a.id = e.article_id
WHERE e.approved = 1                           -- Iterative filter on embedding table
  AND a.category IN ('Technology', 'Science')  -- Filter on main table
  AND a.views > 50000
ORDER BY vs.distance;

Fonctionnalités clés de cet exemple :

  • Étendue de l’alias de table : l’alias e à partir de TABLE = wikipedia_articles_embeddings AS e celui-ci est disponible dans la clause WHERE pour le filtrage itératif avec les derniers index de version

Comportements attendus

Erreur utilisant la syntaxe héritée

Si vous tentez d’utiliser le TOP_N paramètre lors VECTOR_SEARCH de l’interrogation d’une table avec un index vectoriel de version le plus récent, SQL Server retourne l’erreur suivante :

Msg 42274, Level 16, State 1
Vector search with version 3 index does not support explicit TOP_N parameter.

Pour résoudre cette erreur :

  1. Supprimer le TOP_N paramètre de la VECTOR_SEARCH fonction
  2. Utiliser SELECT TOP (N) WITH APPROXIMATE la syntaxe à la place

Incorrect (génère une erreur avec l’index de version le plus récent) :

SELECT TOP (10) 
    t.id,
    r.distance
FROM VECTOR_SEARCH(
        TABLE = dbo.wikipedia_articles AS t,
        COLUMN = title_vector,
        SIMILAR_TO = @qv,
        METRIC = 'cosine',
        TOP_N = 10  -- This parameter causes the error with latest version indexes
    ) AS r;

Correct (fonctionne avec l’index de version le plus récent) :

SELECT TOP (10) WITH APPROXIMATE  -- Specify TOP and WITH APPROXIMATE here
    t.id,
    r.distance
FROM VECTOR_SEARCH(
        TABLE = dbo.wikipedia_articles AS t,
        COLUMN = title_vector,
        SIMILAR_TO = @qv,
        METRIC = 'cosine'
        -- No TOP_N parameter
    ) AS r
ORDER BY r.distance;

Comportement de filtrage itératif

La dernière version introduit des améliorations significatives par rapport aux versions antérieures de l’index vectoriel :

Aspect Version antérieure Version la plus récente
Application de prédicat Les prédicats relationnels ont été appliqués après la recherche vectorielle a retourné un nombre fixe de voisins les plus proches (post-filtrage uniquement) Les prédicats relationnels sont appliqués pendant le processus de recherche vectorielle (filtrage itératif)
Complétivité des résultats Les requêtes pouvaient retourner moins de lignes ( ou pas de lignes) si les voisins les plus proches initiaux n’ont pas satisfait les filtres, même lorsque les lignes éligibles existaient Les requêtes retournent le nombre attendu de lignes lorsque des données éligibles existent, sans réglage manuel ni réécriture des requêtes
Réglage TOP (N) Les utilisateurs ont souvent dû deviner ou oversample TOP (N) valeurs pour compenser le post-filtrage Il n’est pas nécessaire de deviner les valeurs TOP (N). Le moteur recherche jusqu’à ce que suffisamment de lignes éligibles soient trouvées ou que l’espace de recherche soit épuisé
Optimisation des requêtes Sans objet SQL Server sélectionne automatiquement la stratégie d’exécution la plus efficace, notamment le basculement entre les recherches d’index vectoriel et les analyses kNN le cas échéant

Pour obtenir un exemple pratique de filtrage itératif, consultez l’exemple C : Recherche vectorielle avec filtrage itératif.

Exigences de clause ORDER BY

Lors de l’utilisation SELECT TOP (N) WITH APPROXIMATE, la clause ORDER BY a des exigences spécifiques :

  • ORDER BY doit être présent : les requêtes sans clause ORDER BY échouent avec une erreur .
  • Colonne de distance uniquement autorisée : la clause ORDER BY doit référencer uniquement la colonne de distance du jeu de résultats VECTOR_SEARCH. L’inclusion de colonnes supplémentaires échoue avec une erreur. Pour trier par plusieurs colonnes, utilisez le modèle de sous-requête décrit dans plusieurs colonnes ORDER BY.
  • Ordre croissant uniquement : la colonne de distance doit être triée dans l’ordre croissant (ASC). L’ordre décroissant (DESC) n’est pas pris en charge.

COMMANDE VALIDE BY :

SELECT TOP (10) WITH APPROXIMATE
    t.id,
    t.title,
    r.distance
FROM VECTOR_SEARCH(
    TABLE = products,
    COLUMN = embedding,
    SIMILAR_TO = @query_vector,
    METRIC = 'cosine'
) AS r
INNER JOIN products t ON t.id = r.id
ORDER BY r.distance;  -- ✓ Valid

Modèles ORDER BY non valides :

-- Missing ORDER BY
SELECT TOP (10) WITH APPROXIMATE
    r.distance
FROM VECTOR_SEARCH(
    TABLE = products,
    COLUMN = embedding,
    SIMILAR_TO = @query_vector,
    METRIC = 'cosine'
) AS r;
-- ✗ Error Msg 42248: APPROXIMATE cannot be used in a query without ORDER BY

-- Multiple columns in ORDER BY
SELECT TOP (10) WITH APPROXIMATE
    t.title,
    r.distance
FROM VECTOR_SEARCH(
    TABLE = products,
    COLUMN = embedding,
    SIMILAR_TO = @query_vector,
    METRIC = 'cosine'
) AS r
INNER JOIN products t ON t.id = r.id
ORDER BY r.distance, t.title;
-- ✗ Error Msg 42271: TOP WITH APPROXIMATE and VECTOR_SEARCH requires ORDER BY 
-- on distance column ascending, and no other columns

-- Descending order
SELECT TOP (10) WITH APPROXIMATE
    r.distance
FROM VECTOR_SEARCH(
    TABLE = products,
    COLUMN = embedding,
    SIMILAR_TO = @query_vector,
    METRIC = 'cosine'
) AS r
ORDER BY r.distance DESC;
-- ✗ Error Msg 42271: TOP WITH APPROXIMATE and VECTOR_SEARCH requires ORDER BY 
-- on distance column ascending, and no other columns

Comportement sans index vectoriel

VECTOR_SEARCH peut exécuter des requêtes même lorsqu’aucun index vectoriel n’existe sur la colonne cible. Sans index, la requête effectue une recherche complète de table (k-nearest voisin (kNN) pour calculer les distances pour toutes les lignes.

Comportement de requête sans TOP WITH APPROXIMATE

Lorsque vous utilisez VECTOR_SEARCH sans SELECT TOP (N) WITH APPROXIMATE, le comportement de la requête dépend de la présence et des TOPORDER BY clauses :

  • Aucun TOP, aucun ORDER BY ou ORDER BY non-distance : analyse complète de la table (recherche par force brute) qui calcule et retourne des distances pour toutes les lignes
  • TOP (pas APPROXIMATIF) avec la distance ORDER BY : s’exécute en tant que recherche kNN (k-nearest neighbors), qui est une recherche exacte voisin la plus proche

Exemple : analyse complète avec colonne de distance :

-- Returns all rows with calculated distances
SELECT 
    t.id,
    t.title,
    r.distance
FROM VECTOR_SEARCH(
    TABLE = dbo.wikipedia_articles AS t,
    COLUMN = title_vector,
    SIMILAR_TO = @qv,
    METRIC = 'cosine'
) AS r
ORDER BY t.id;  -- Not ordering by distance

Exemple : recherche kNN (voisins les plus proches exacts) :

-- Returns exact top 10 nearest neighbors using kNN
SELECT TOP (10)
    t.id,
    t.title,
    r.distance
FROM VECTOR_SEARCH(
    TABLE = dbo.wikipedia_articles AS t,
    COLUMN = title_vector,
    SIMILAR_TO = @qv,
    METRIC = 'cosine'
) AS r
ORDER BY r.distance;  -- No WITH APPROXIMATE = exact kNN

L’utilisation SELECT TOP (N) WITH APPROXIMATE sans VECTOR_SEARCH fonction dans la requête entraîne une erreur. La WITH APPROXIMATE clause nécessite qu’une VECTOR_SEARCH fonction soit présente.

Incorrect - Cette requête échoue :

-- Error: WITH APPROXIMATE requires VECTOR_SEARCH
SELECT TOP (10) WITH APPROXIMATE
    id,
    title,
    VECTOR_DISTANCE('cosine', title_vector, @qv) AS distance
FROM dbo.wikipedia_articles
WHERE title_vector IS NOT NULL
ORDER BY VECTOR_DISTANCE('cosine', title_vector, @qv);

Correct - Utilisez VECTOR_SEARCH :

-- Correct: WITH APPROXIMATE with VECTOR_SEARCH
SELECT TOP (10) WITH APPROXIMATE
    t.id,
    t.title,
    r.distance
FROM VECTOR_SEARCH(
    TABLE = dbo.wikipedia_articles AS t,
    COLUMN = title_vector,
    SIMILAR_TO = @qv,
    METRIC = 'cosine'
) AS r
ORDER BY r.distance;

Restrictions TRUNCATE TABLE

Les tables avec des index vectoriels ne peuvent pas être tronquées à l’aide TRUNCATE TABLEde . Pour supprimer toutes les données d’une table indexée par vecteur :

  1. Supprimer l’index vectoriel
  2. Tronquer la table
  3. Remplir à nouveau la table avec au moins 100 lignes
  4. Recréer l’index vectoriel

Exemple de flux de travail :

-- Step 1: Drop the vector index
DROP INDEX idx_vector ON wikipedia_articles;

-- Step 2: Truncate the table
TRUNCATE TABLE wikipedia_articles;

-- Step 3: Repopulate with data (at least 100 rows)
-- ... insert operations ...

-- Step 4: Recreate the vector index
CREATE VECTOR INDEX idx_vector 
ON wikipedia_articles(title_vector)
WITH (METRIC = 'cosine');

Vous pouvez utiliser des indicateurs de table avec la fonction pour contrôler le VECTOR_SEARCH comportement d’exécution des requêtes. L’indicateur FORCE_ANN_ONLY de table force l’optimiseur de requête à utiliser uniquement l’index voisin le plus proche (ANN), même lorsque l’optimiseur peut choisir une autre stratégie d’exécution.

Syntaxe :

FROM VECTOR_SEARCH(
    TABLE      = table_name,
    COLUMN     = column_name,
    SIMILAR_TO = vector_value,
    METRIC     = 'metric_name'
) AS alias WITH (FORCE_ANN_ONLY)

Exemple :

L’exemple suivant force l’utilisation de l’index voisin le plus proche approximatif pour la requête de recherche vectorielle :

DECLARE @qembedding VECTOR(1536) = AI_GENERATE_EMBEDDINGS(N'artificial intelligence' USE MODEL Ada2Embeddings);

SELECT TOP 50 WITH APPROXIMATE
    t.id,
    t.title,
    r.distance
FROM VECTOR_SEARCH(
    TABLE      = dbo.wikipedia_articles AS t,
    COLUMN     = title_vector,
    SIMILAR_TO = @qembedding,
    METRIC     = 'cosine'
) AS r WITH (FORCE_ANN_ONLY)
ORDER BY r.distance;

Utilisez FORCE_ANN_ONLY quand vous souhaitez vous assurer que la requête utilise la stratégie d’index voisin la plus proche approximative, en remplaçant la sélection automatique de la stratégie d’optimiseur.

Note

L’utilisation FORCE_ANN_ONLY nécessite les deux :

  • Index vectoriel sur la colonne cible
  • SELECT TOP (N) WITH APPROXIMATE dans la requête

Si l’une ou l’autre exigence est manquante, la requête échoue car elle ne peut pas utiliser la stratégie de voisin la plus proche approximative que l’indicateur force.

Combinaison de la recherche vectorielle avec d’autres opérations SQL

La VECTOR_SEARCH fonction avec des TOP (N) WITH APPROXIMATE exigences spécifiques pour son utilisation. Certaines opérations SQL peuvent être utilisées directement avec la recherche vectorielle, tandis que d’autres nécessitent un modèle de sous-requête.

Opérations nécessitant un modèle de sous-requête

Lorsque vous devez effectuer des opérations qui ne sont pas directement compatibles avec TOP (N) WITH APPROXIMATE, utilisez la recherche vectorielle dans une sous-requête (requête interne), puis appliquez vos opérations dans la requête externe. Ce modèle conserve les avantages en termes de performances de la recherche vectorielle approximative tout en activant la fonctionnalité SQL complète.

Conseil / Astuce

Le modèle de sous-requête fonctionne pour toutes les opérations qui ne peuvent pas être combinées directement avec TOP (N) WITH APPROXIMATE. Appliquez la recherche vectorielle dans la requête interne, puis utilisez n’importe quelle opération SQL dans la requête externe.

Scénarios courants

Le tableau suivant répertorie les opérations qui nécessitent le modèle de sous-requête :

Operation Exemple de cas d’usage
REGROUPER PAR Calculer les statistiques par catégorie
Fonctions d'agrégation Nombre global, AVG, MIN, MAX entre les résultats
Fonctions de fenêtre ROW_NUMBER, RANK, DENSE_RANK, NTILE
Définir des opérations UNION, UNION ALL, EXCEPT, INTERSECT
Colonnes ORDER BY multiples Trier par distance, puis par date ou titre
DISTINCTIF Supprimer les résultats dupliqués
CROSS APPLY Appliquer la recherche vectorielle par ligne à partir d’une table externe

FONCTIONS GROUP BY et d’agrégation

L’exemple suivant recherche la distance moyenne des articles correspondants principaux par catégorie. Pour cet exemple, une category colonne a été ajoutée à la wikipedia_articles table pour classifier les articles.

DECLARE @qv VECTOR(1536) = AI_GENERATE_EMBEDDINGS(N'machine learning' USE MODEL Ada2Embeddings);

SELECT 
    category,
    COUNT(*) AS article_count,
    AVG(distance) AS avg_distance,
    MIN(distance) AS closest_match
FROM (
    SELECT TOP (100) WITH APPROXIMATE
        t.id,
        t.title,
        t.category,
        r.distance
    FROM VECTOR_SEARCH(
        TABLE = dbo.wikipedia_articles AS t,
        COLUMN = title_vector,
        SIMILAR_TO = @qv,
        METRIC = 'cosine'
    ) AS r
    ORDER BY r.distance
) AS vector_results
GROUP BY category
ORDER BY avg_distance;

Fonctions de fenêtre

L’exemple suivant classe les articles par similarité et affecte des quartiles.

DECLARE @qv VECTOR(1536) = AI_GENERATE_EMBEDDINGS(N'neural networks' USE MODEL Ada2Embeddings);

SELECT 
    id,
    title,
    category,
    distance,
    ROW_NUMBER() OVER (ORDER BY distance) AS rank,
    NTILE(4) OVER (ORDER BY distance) AS quartile
FROM (
    SELECT TOP (100) WITH APPROXIMATE
        t.id,
        t.title,
        t.category,
        r.distance
    FROM VECTOR_SEARCH(
        TABLE = dbo.wikipedia_articles AS t,
        COLUMN = title_vector,
        SIMILAR_TO = @qv,
        METRIC = 'cosine'
    ) AS r
    ORDER BY r.distance
) AS vector_results
WHERE distance < 0.5
ORDER BY rank;

Définir des opérations (UNION, INTERSECT, EXCEPT)

L’exemple suivant combine les résultats de deux requêtes de recherche différentes à l’aide d’UNION.

DECLARE @qv1 VECTOR(1536) = AI_GENERATE_EMBEDDINGS(N'artificial intelligence' USE MODEL Ada2Embeddings);
DECLARE @qv2 VECTOR(1536) = AI_GENERATE_EMBEDDINGS(N'machine learning' USE MODEL Ada2Embeddings);

SELECT id, title, 'AI Search' AS source
FROM (
    SELECT TOP (50) WITH APPROXIMATE
        t.id,
        t.title,
        r.distance
    FROM VECTOR_SEARCH(
        TABLE = dbo.wikipedia_articles AS t,
        COLUMN = title_vector,
        SIMILAR_TO = @qv1,
        METRIC = 'cosine'
    ) AS r
    ORDER BY r.distance
) AS ai_results

UNION

SELECT id, title, 'ML Search' AS source
FROM (
    SELECT TOP (50) WITH APPROXIMATE
        t.id,
        t.title,
        r.distance
    FROM VECTOR_SEARCH(
        TABLE = dbo.wikipedia_articles AS t,
        COLUMN = title_vector,
        SIMILAR_TO = @qv2,
        METRIC = 'cosine'
    ) AS r
    ORDER BY r.distance
) AS ml_results
ORDER BY id;

DISTINCTIF

L’exemple suivant obtient des catégories distinctes des articles correspondants principaux.

DECLARE @qv VECTOR(1536) = AI_GENERATE_EMBEDDINGS(N'deep learning' USE MODEL Ada2Embeddings);

SELECT DISTINCT category
FROM (
    SELECT TOP (100) WITH APPROXIMATE
        t.id,
        t.category,
        r.distance
    FROM VECTOR_SEARCH(
        TABLE = dbo.wikipedia_articles AS t,
        COLUMN = title_vector,
        SIMILAR_TO = @qv,
        METRIC = 'cosine'
    ) AS r
    ORDER BY r.distance
) AS vector_results
WHERE distance < 0.7
ORDER BY category;

Colonnes ORDER BY multiples

L’exemple suivant trie par distance, puis par titre pour les liens.

DECLARE @qv VECTOR(1536) = AI_GENERATE_EMBEDDINGS(N'quantum computing' USE MODEL Ada2Embeddings);

SELECT 
    id,
    title,
    category,
    distance
FROM (
    SELECT TOP (100) WITH APPROXIMATE
        t.id,
        t.title,
        t.category,
        r.distance
    FROM VECTOR_SEARCH(
        TABLE = dbo.wikipedia_articles AS t,
        COLUMN = title_vector,
        SIMILAR_TO = @qv,
        METRIC = 'cosine'
    ) AS r
    ORDER BY r.distance
) AS vector_results
ORDER BY distance, title;

CROSS APPLY

Lorsque vous utilisez SELECT TOP (N) WITH APPROXIMATE , VECTOR_SEARCHvous ne pouvez pas utiliser CROSS APPLY ou OUTER APPLY dans la même FROM clause. Cela s’applique même s’il n’existe aucune référence externe dans la VECTOR_SEARCH fonction.

Une requête avec laquelle CROSS APPLY effectuerait logiquement plusieurs recherches vectorielles (une par ligne à partir de la table externe) et fusionnerait tous les résultats dans un flux ordonné unique. L’algorithme voisin le plus proche approximatif ne peut pas fusionner efficacement les résultats de plusieurs recherches vectorielles indépendantes tout en conservant les garanties approximatives et les caractéristiques de performances.

Modèle qui génère une erreur :

-- This query is NOT supported
SELECT TOP (100) WITH APPROXIMATE
    o.id,
    vs.title,
    vs.distance
FROM Orders AS o
    CROSS APPLY VECTOR_SEARCH(
        TABLE = Products,
        COLUMN = embedding,
        SIMILAR_TO = o.customer_preference_vector,
        METRIC = 'cosine'
    ) AS vs
WHERE o.order_date > '2026-01-01'
ORDER BY vs.distance;

Ce modèle tente de trouver des produits similaires pour la préférence client de chaque commande, mais ne peut pas être exécuté avec un plan de recherche vectorielle approximatif.

Modèle recommandé :

Pour obtenir des résultats similaires, utilisez une sous-requête avec TOP (N) WITH APPROXIMATE en CROSS APPLY soi :

-- This query IS supported
SELECT
    o.id,
    vs.title,
    vs.distance
FROM Orders AS o
    CROSS APPLY (
        SELECT TOP (10) WITH APPROXIMATE
            p.title,
            r.distance
        FROM VECTOR_SEARCH(
            TABLE = Products AS p,
            COLUMN = embedding,
            SIMILAR_TO = o.customer_preference_vector,
            METRIC = 'cosine'
        ) AS r
        ORDER BY r.distance
    ) AS vs
WHERE o.order_date > '2026-01-01';

Dans ce modèle :

  • Chaque recherche vectorielle est limitée aux 10 premiers résultats dans la sous-requête
  • La requête externe n’utilise pas WITH APPROXIMATE
  • Les résultats sont correctement délimités par ligne à partir de la table externe

Opérations qui fonctionnent directement

Les opérations suivantes peuvent être utilisées directement avec VECTOR_SEARCH sans nécessiter de sous-requête :

Contenu connexe

  • Last updated on