CREATE VECTOR INDEX (Transact-SQL)

S'applique à : SQL Server 2025 (17.x) Azure SQL DatabaseAzure SQL Managed InstanceBase de données SQL dans Microsoft Fabric

Créez un index approximatif sur une colonne vectorielle pour améliorer les performances des recherches de voisins les plus proches. Pour en savoir plus sur le fonctionnement de l’indexation vectorielle et de la recherche vectorielle, ainsi que sur les différences entre la recherche exacte et la recherche approximative, voir Recherche vectorielle et indexes vectoriels dans le SQL Moteur de base de données.

Disponibilité des fonctionnalités

• Vector index et VECTOR_SEARCH sont généralement disponibles (GA) dans Azure SQL Database, la base de données SQL dans Microsoft Fabric, et Azure SQL Managed Instance avec la politique de mise à jourAlways-up-to-date.
• Vector index et VECTOR_SEARCH sont des fonctionnalités d’aperçu dans SQL Server 2025 (17.x) et dans Azure SQL Managed Instance avec la politique de mise à jour SQL Server 2025.

Fonctionnalité d’aperçu de SQL Server 2025

Dans SQL Server 2025 et Azure SQL Managed Instance dans la politique de mise à jourde SQL Server 2025, les index vectoriels et la VECTOR_SEARCH fonction sont en prévisualisation et sujets à modification. Pour utiliser cette fonctionnalité, vous devez activer la PREVIEW_FEATURESconfiguration à portée de données (cale de données).

Vérifiez les limitations actuelles avant de l’utiliser.

Syntaxe

Conventions de la syntaxe Transact-SQL

CREATE VECTOR INDEX index_name
ON object ( vector_column )
[ WITH (
    [ , ] METRIC = { 'cosine' | 'dot' | 'euclidean' }
    [ [ , ] TYPE = 'DiskANN' ]
    [ [ , ] MAXDOP = max_degree_of_parallelism ]
) ]
[ ON { filegroup_name | "default" } ]
[;]

Les arguments

index_name

Nom de l’index. Les noms d’index doivent être uniques dans une table, mais ne doivent pas être uniques dans une base de données. Les noms d’index doivent suivre les règles des identificateurs.

objet

Table sur laquelle l’index est créé. Il doit s’agir d’une table de base. Les vues, les tables temporaires, locales et globales, ne sont pas prises en charge.

vector_column

Colonne à utiliser pour créer l’index vectoriel. Il doit être de type vecteur .

MÉTRIQUE

Chaîne portant le nom de la métrique de distance à utiliser pour calculer la distance entre les deux vecteurs donnés. Les métriques de distance suivantes sont prises en charge :

• cosine - Distance cosinus
• euclidean - Distance euclide
• dot - (Négatif) Produit point

TYPE

Type d’algorithme ANN utilisé pour générer l’index. Seule DiskANN est actuellement prise en charge. DiskANN est la valeur par défaut.

MAXDOP

Remplace l’option de configuration max degree of parallelism pour l’opération d’index. Pour plus d’informations, consultez Configuration du serveur : degré maximal de parallélisme. Permet MAXDOP de limiter le degré de parallélisme et la consommation de ressources résultante pour une opération de génération d’index.

max_degree_of_parallelism peut avoir la valeur :

• 1

  Supprime la création de plans parallèles.

• >1

  Limite le degré maximal de parallélisme utilisé dans une opération d’index parallèle au nombre spécifié ou inférieur en fonction de la charge de travail système actuelle.

• 0 (valeur par défaut)

  Utilise le degré de parallélisme spécifié au niveau du serveur, de la base de données ou du groupe de charge de travail, sauf s’il est réduit en fonction de la charge de travail système actuelle.

  Pour plus d’informations, consultez Configurer des opérations d’index parallèles.

  Les opérations d’index parallèles ne sont pas disponibles dans toutes les éditions de SQL Server. Pour une liste des fonctionnalités prises en charge par les éditions de SQL Server, voir Éditions et fonctionnalités prises en charge de SQL Server 2025.

Mettre à niveau des index vectoriels vers la dernière version

Les index vectoriels nouvellement créés utilisent automatiquement la structure de données la plus récente, qui fournit :

• 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 désormais effectuer INSERT, UPDATE, DELETE, et MERGE opérations tout en maintenant la fonctionnalité d’index vectoriel grâce à une maintenance automatique de l’index en temps réel.
• Filtrage itératif : applique les prédicats dans la WHERE clause pendant le processus de recherche vectoriel, et non après la récupération.
• Piloté par l’optimiseur : 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 la requête.
• Quantification avancée : Intègre des techniques de quantification vectorielle pour offrir une meilleure efficacité de stockage et une performance de requête plus rapide. Ces optimisations sont transparentes pour les utilisateurs.

Pour plus de détails sur les limitations antérieures des versions des indices vectoriels, voir la section Limitations et considérations.

Migration à partir des versions antérieures de l’index vectoriel

Pour activer les dernières fonctionnalités, vous devez supprimer et recréer des index vectoriels utilisant une version antérieure. Cette section explique comment identifier, migrer et vérifier les versions d’index vectorielles.

Étape 1 : Identifier les index vectoriels existants

Utilisez la requête suivante pour identifier les index vectoriels qui nécessitent une migration :

SELECT
    i.name AS index_name,
    t.name AS table_name,
    JSON_VALUE(v.build_parameters, '$.Version') AS index_version,
    CASE
        WHEN JSON_VALUE(v.build_parameters, '$.Version') >= '3'
            THEN 'Uses latest version (no migration required)'
        WHEN JSON_VALUE(v.build_parameters, '$.Version') < '3'
            THEN 'Created using an earlier version (migration recommended)'
        ELSE 'Unknown format'
    END AS migration_status
FROM sys.vector_indexes AS v
    INNER JOIN sys.indexes AS i
        ON v.object_id = i.object_id
        AND v.index_id = i.index_id
    INNER JOIN sys.tables AS t
        ON v.object_id = t.object_id
ORDER BY t.name, i.name;

Comment interpréter les résultats

Utilise la dernière version

• Prend déjà en charge le filtrage itératif, la prise en charge complète du DML, l’exécution pilotée par optimiseur et une quantification améliorée.
• Aucune migration requise.

Créé à l’aide d’une version antérieure

• Utilise un comportement post-filtre hérité.
• Ne prend pas en charge les dernières capacités de recherche vectorielle.
• La migration est fortement recommandée pour garantir la compatibilité future.

Étape 2 : Supprimer et recréer l’index vectoriel

Vous ne pouvez pas mettre à jour les index vectoriels qui utilisent un format antérieur. Pour activer les fonctionnalités DiskANN les plus récentes, supprimez et recréez l’index.

Supprimer l’index existant

DROP INDEX vec_idx ON dbo.wikipedia_articles;

Recréer l’index

CREATE VECTOR INDEX vec_idx
    ON dbo.wikipedia_articles (title_vector)
    WITH (
        TYPE = 'DISKANN',
        METRIC = 'COSINE'
    );

Étape 3 : Vérifier la version de l’index

Après avoir recréé l’index, vérifiez qu’il utilise la dernière version :

SELECT
    i.name AS index_name,
    t.name AS table_name,
    JSON_VALUE(v.build_parameters, '$.Version') AS index_version
FROM sys.vector_indexes AS v
    INNER JOIN sys.indexes AS i
        ON v.object_id = i.object_id
        AND v.index_id = i.index_id
    INNER JOIN sys.tables AS t
        ON v.object_id = t.object_id
WHERE i.name = 'vec_idx';

La index_version colonne doit s’afficher 3 pour la dernière version.

Comportement d’erreur avec incompatibilité de version

Si vous tentez d’utiliser le TOP_N paramètre avec VECTOR_SEARCH 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, supprimez le TOP_N paramètre et VECTOR_SEARCH utilisez plutôt la SELECT TOP (N) WITH APPROXIMATE syntaxe. Pour plus d’informations, consultez Erreur à l’aide de la syntaxe héritée.

Limitations et considérations

Limitations antérieures de la version de l’index vectoriel

Les versions antérieures à index vectoriel présentent les limitations suivantes. Pour vérifier votre version d’index, consultez Vérifier la version de l’index.

• Après filtrage uniquement : Les prédicats ne s’appliquent qu’après la récupération du vecteur, pas pendant le processus de recherche. Ce comportement peut entraîner moins de lignes que prévu lors de l’application des filtres.

• Tables en lecture seule : les tables avec des index vectoriels sont en lecture seule. Vous ne pouvez pas effectuer d’opérations DML (INSERT, UPDATE, DELETE, MERGE) après avoir créé l’indice vectoriel. Utilisez la configuration délimitée à la ALLOW_STALE_VECTOR_INDEX base de données pour activer les opérations DML si vous pouvez tolérer des résultats de recherche obsolètes.

• Réglage manuel TOP_N : Vous devez ajuster manuellement le TOP_N paramètre pour VECTOR_SEARCH compenser le post-filtrage. Il faut souvent des valeurs surdimensionnées pour obtenir le nombre de résultats souhaité.

Limitations actuelles (s’applique également à la dernière version)

La préversion actuelle présente les limitations suivantes :

• On ne peut pas partitionner les index vectoriels.

• La table doit avoir un index groupé de clé primaire sur une colonne int .

• Les index vectoriels ne sont pas répliqués sur les abonnés.

• Vous ne pouvez pas tronquer des tables avec des indices vectoriels en utilisant TRUNCATE TABLE. Pour supprimer toutes les données, supprimez d’abord l’index vectoriel, tronquez la table, remplissez à nouveau avec au moins 100 lignes, puis recréez l’index. Pour plus d’informations, voir TRUNCATE TABLE restrictions.

• Les index vectoriels ne peuvent pas être déployés avec DacPac. Vous pouvez déployer des bases de données contenant des index vectoriels avec BACPAC à partir de la version 170.5.96 de DacFx. Les indices vectoriels sont créés après le chargement des données de la table, et la table indexée doit contenir au moins 100 lignes avec des valeurs nonNULL vectorielles.

  Lors d’un déploiement DACPAC uniquement schéma, le déploiement peut réussir sans créer l’indice vectoriel si la table cible contient moins de 100 lignes avec des valeurs nonNULL vectorielles. DacFx ne crée pas automatiquement l’index sauté lorsque les lignes sont ajoutées plus tard. Après avoir chargé au moins 100 lignes qualificatives, créez l’index vectoriel en utilisant un script post-déploiement, en publiant à nouveau le DACPAC, ou en exécutant CREATE VECTOR INDEX.

  Après une importation ou un déploiement, vérifiez que l’indice vectoriel a été créé en interrogeant sys.vector_indexes.

  Comme solution de contournement avant la version 170.5.96 de DacFx, supprimez les index vectoriels avant d’exporter la base de données, puis recréez les index après l’importation.

Configuration minimale requise pour les données

Les indices vectoriels nécessitent un nombre minimum de lignes avec des valeurs nonNULL vectorielles avant de pouvoir créer l’index.

• Nombre minimal de lignes : La table doit comporter au moins 100 lignes avec des valeurs nonNULL vectorielles.
• Comportement d’erreur : Si vous essayez de créer un index vectoriel sur une table de moins de 100 lignes, l’opération échoue et retourne l’erreur Msg 42266.

Exemple d’erreur :

Msg 42266, Level 16, State 1
Cannot create a vector index. The table contains only 8 rows with non-null vectors, 
but at least 100 are required for vector index creation.

Bonne pratique : remplissez la table avec au moins 100 lignes avant de créer l’index vectoriel. Pour les scénarios de développement et de test où il faut moins de lignes, cela VECTOR_SEARCH fonctionne sans index en utilisant une approche de scan par force brute. Cependant, cette méthode dégrade les performances avec des ensembles de données plus volumineux.

Prise en charge de DML

Lorsque vous créez un index vectoriel DiskANN en utilisant la dernière version, la table n’est plus en lecture seule. Vous pouvez modifier les données en utilisant des opérations de langage de manipulation de données (DML) standard, et les modifications apparaissent automatiquement dans les résultats de recherche vectorielle.

Cette fonctionnalité rend la recherche vectorielle adaptée aux charges de travail transactionnelles actives où les données changent au fil du temps.

Notes de comportement

• Les opérations DML ne nécessitent pas de suppression ou de reconstruction de l’index vectoriel.
• Les modifications sont visibles pour les requêtes de recherche vectorielle après la validation de la transaction.
• Pour le remplacement des données à grande échelle (par exemple, la suppression de la plupart des lignes et l’insertion d’un ensemble entièrement nouveau d’incorporations), envisagez de supprimer et de recréer l’index vectoriel après la charge des données pour garantir une qualité de recherche optimale.

Surveillance de la maintenance de l’index vectoriel

Les index vectoriels effectuent une maintenance en arrière-plan pour incorporer des modifications DML. Utilisez la vue de gestion dynamique sys.dm_db_vector_indexes pour surveiller l’état de la tâche d’intégrité et de maintenance des index.

Combinaison d’index vectoriels avec des index traditionnels

Les index vectoriels fonctionnent en même temps que les index B-tree traditionnels pour fournir des performances de requête optimales. Lors de l’utilisation du filtrage itératif avec VECTOR_SEARCH, envisagez de créer des index traditionnels sur des colonnes utilisées dans les prédicats de filtre.

Pour plus d’informations sur le comportement de filtrage itératif et sur la façon dont il diffère des versions antérieures, consultez le comportement de filtrage itératif.

Exemple de scénario :

-- Create vector index for similarity search
CREATE VECTOR INDEX idx_embeddings_vector
ON product_embeddings(embedding)
WITH (METRIC = 'cosine');

-- Create traditional index for filter columns
CREATE NONCLUSTERED INDEX idx_embeddings_filters
ON product_embeddings(category);

Avantages en matière de performances :

Lors de l’exécution de requêtes avec un filtrage itératif, l’optimiseur de requête SQL Server utilise les deux types d’index :

DECLARE @qv VECTOR(1536) = AI_GENERATE_EMBEDDINGS(N'wireless headphones' USE MODEL EmbeddingModel);

SELECT TOP (10) WITH APPROXIMATE
    p.name,
    p.price,
    vs.distance
FROM products p
INNER JOIN VECTOR_SEARCH(
    TABLE = product_embeddings AS e,
    COLUMN = embedding,
    SIMILAR_TO = @qv,
    METRIC = 'cosine'
) AS vs ON p.id = e.product_id
WHERE e.approved = 1             
  AND e.category = 'Electronics'  -- Can use traditional index
ORDER BY vs.distance;

Dans cette requête :

• L’index vectoriel identifie des incorporations similaires basées sur le vecteur de requête
• Index traditionnel sur (category) les filtres candidats efficacement pendant le processus de recherche itératif

Cette stratégie composite peut améliorer considérablement les performances des requêtes par rapport à l’utilisation d’un index vectoriel, en particulier lorsque les prédicats de filtre ont une sélectivité élevée.

Conseils de qualité et de maintenance des données pour les index vectoriels

Éviter les jeux de données avec des incorporations en double élevée

L’indexation vectorielle fonctionne mieux lorsque les incorporations représentent un contenu sémantique diversifié. N’utilisez pas de jeux de données avec une forte proportion de vecteurs doublés pour l’indexation vectorielle.

Une duplication élevée peut entraîner :

• Mauvaise qualité des résultats : les vecteurs dupliqués apparaissent à plusieurs reprises dans les résultats, mettant en évidence des correspondances sémantiques plus pertinentes.
• Réduction de l’efficacité : les incorporations en double déplacent de meilleurs voisins, réduisant ainsi l’utilité de la recherche de similarité.
• Utilisation inutile des ressources : les index vectoriels sont coûteux à créer et à gérer, et les doublons ajoutent des coûts sans ajouter de valeur.

Bonne pratique : Dédupliquer les incorporations avant de créer un index vectoriel pour améliorer les performances et la qualité des résultats.

Scénarios de remplacement de données à grande échelle

Les index vectoriels prennent en charge les insertions, les mises à jour et les suppressions. Cependant, lorsque vous remplacez la plupart ou la totalité des embeddings — par exemple, en réintégrant un jeu de données par un nouveau modèle — l’indice existant peut ne plus refléter la nouvelle distribution des données.

Dans les scénarios de remplacement à grande échelle :

• Les requêtes de recherche vectorielle continuent de fournir des résultats valides.
• La qualité du rappel et du classement pourrait se dégrader, car la structure de l’indice a été conçue pour une distribution d’embedding différente.

Bonne pratique : lors de l’exécution d’un remplacement de données quasi complet (suppression et insertion de nouvelles incorporations), supprimez et recréez l’index vectoriel après le chargement des nouvelles données. La recréation de l’index garantit qu’elle est optimisée pour la nouvelle distribution d’incorporation et restaure le comportement de requête prévisible.

Problèmes connus

Pour plus d’informations, consultez les problèmes connus.

Autorisations

Il faut ALTER une permission sur la table.

Exemples

Téléchargez et importez l’article Wikipédia avec l’exemple d’incorporation de vecteurs .

Ces exemples supposent un tableau nommé wikipedia_articles avec une colonne title_vector de caractères vector qui stocke les insertions de titres des articles Wikipédia. Il title_vector utilise un modèle d’immersion comme text-embedding-ada-002 ou text-embedding-3-small, qui renvoie des vecteurs avec 1 536 dimensions.

Pour plus d’exemples, y compris des solutions de bout en bout, consultez le dépôt Azure SQL Database Vector Search Samples sur GitHub.

Exemple 1

L’exemple suivant crée un index vectoriel sur la colonne à l’aide title_vector de la cosine métrique.

CREATE VECTOR INDEX vec_idx
    ON [dbo].[wikipedia_articles] ([title_vector])
        WITH (METRIC = 'COSINE', TYPE = 'DISKANN');

Exemple 2

L’exemple suivant crée un indice vectoriel sur la title_vector colonne en utilisant la métrique produit (négative dot ). Il limite le parallélisme à 8 et stocke le vecteur dans le SECONDARY groupe de fichiers.

CREATE VECTOR INDEX vec_idx
    ON [dbo].[wikipedia_articles] ([title_vector])
        WITH (METRIC = 'DOT', TYPE = 'DISKANN', MAXDOP = 8)
    ON [SECONDARY];

Exemple 3

Cet exemple utilise CREATE VECTOR INDEX et la fonction associée VECTOR_SEARCH . Les incorporations sont simulées. Dans un scénario réel, générez des embeddings en utilisant un modèle d’embedding et AI_GENERATE_EMBEDDINGS, ou utilisez une bibliothèque externe telle qu’OpenAI SDK.

Le bloc de code suivant illustre CREATE VECTOR INDEX les incorporations fictives :

1. Activez la fonction de prévisualisation (requise uniquement pour SQL Server 2025 ; pas 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 :

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
    ) AS s
ORDER BY s.distance, t.title;

Exemple 4 : Utilisation des opérations DML

Les exemples suivants démontrent des opérations DML sur une table avec un indice vectoriel créé en utilisant la dernière version.

Supprimer des lignes

La suppression de lignes les supprime à la fois de la table et des résultats de recherche vectorielle.

DELETE FROM dbo.wikipedia_articles
WHERE id = 12345;

Après la fin de l’opération de suppression, la ligne supprimée n’apparaît plus dans les requêtes de recherche vectorielle.

Insérer de nouvelles lignes

Vous pouvez insérer de nouvelles lignes avec des incorporations, et elles deviennent immédiatement pouvant faire l’objet d’une recherche sans reconstruire l’index.

INSERT INTO dbo.wikipedia_articles (id, title, title_vector)
VALUES (
    99999,
    N'Quantum Computing Basics',
    AI_GENERATE_EMBEDDINGS(N'Quantum Computing Basics' USE MODEL Ada2Embeddings)
);

Les incorporations nouvellement insérées sont automatiquement incorporées dans l’index vectoriel et peuvent être retournées par les requêtes de recherche vectorielle suivantes.

Mettre à jour les lignes existantes

La mise à jour des colonnes vectorielles ou non vectorielles est entièrement prise en charge.

DECLARE @new_embedding VECTOR(1536);
SET @new_embedding = AI_GENERATE_EMBEDDINGS(N'Updated article title' USE MODEL Ada2Embeddings);

UPDATE dbo.wikipedia_articles
SET title_vector = @new_embedding,
    title = N'Updated article title'
WHERE id = 50000;

Si vous mettez à jour une colonne vectorielle, l’index se met à jour en conséquence, donc les recherches vectorielles futures utilisent le nouvel embedding.

Utilisation MERGE pour des opérations complexes

L’instruction MERGE vous permet d’effectuer des opérations d’insertion, de mise à jour et de suppression dans une seule instruction.

MERGE INTO dbo.wikipedia_articles AS target
USING (
    SELECT 
        id,
        title,
        AI_GENERATE_EMBEDDINGS(title USE MODEL Ada2Embeddings) AS title_vector
    FROM dbo.staging_articles
) AS source
ON target.id = source.id
WHEN MATCHED THEN
    UPDATE SET 
        title = source.title,
        title_vector = source.title_vector
WHEN NOT MATCHED BY TARGET THEN
    INSERT (id, title, title_vector)
    VALUES (source.id, source.title, source.title_vector)
WHEN NOT MATCHED BY SOURCE AND target.id > 100000 THEN
    DELETE;

L’index vectoriel se met automatiquement à jour pour refléter tous les changements apportés par l’énoncé MERGE .

Contenu connexe

• Recherche vectorielle et index vectoriels dans le moteur de base de données SQL
• Type de données vectorielles
• VECTOR_SEARCH (Transact-SQL)
• sys.vector_indexes (Transact-SQL)
• sys.dm_db_vector_indexes (Transact-SQL)
• Exemples de recherche vectorielle Azure SQL Database