CREATE VECTOR INDEX (Transact-SQL)

Si applica a: SQL Server 2025 (17.x) Database SQL di AzureIstanza gestita di SQL di AzureDatabase SQL in Microsoft Fabric

Crea un indice approssimato su una colonna vettoriale per migliorare le prestazioni delle ricerche tra vicini più prossimi. Per saperne di più su come funzionano l'indicizzazione vettoriale e la ricerca vettoriale, e sulle differenze tra ricerca esatta e approssimativa, consulta Ricerca vettoriale e indici vettoriali nel SQL motore di database.

Disponibilità della funzionalità

• Vector index e VECTOR_SEARCH sono generalmente disponibili (GA) in database SQL di Azure, database SQL in Microsoft Fabric e Istanza gestita di SQL di Azure con la politica di aggiornamentoAlways-up-to-date.
• Vector index e VECTOR_SEARCH sono funzionalità di anteprima in SQL Server 2025 (17.x) e in Istanza gestita di SQL di Azure con la policy di aggiornamento di SQL Server 2025.

Funzione di anteprima di SQL Server 2025

In SQL Server 2025 e Istanza gestita di SQL di Azure, nella policy di aggiornamentodi SQL Server 2025, gli indici vettoriali e la VECTOR_SEARCH funzione sono in anteprima e soggetti a modifiche. Per utilizzare questa funzione, devi abilitare la PREVIEW_FEATURESconfigurazione con scopo del database.

Controlla le limitazioni attuali prima di usarlo.

Sintassi

Convenzioni relative alla sintassi 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" } ]
[;]

Argomenti

index_name

Nome dell'indice. I nomi degli indici devono essere univoci all'interno di una tabella, ma non devono essere univoci all'interno di un database. I nomi degli indici devono seguire le regole degli identificatori.

oggetto

Tabella in cui viene creato l'indice. Deve essere una tabella di base. Le viste, le tabelle temporanee, sia locali che globali, non sono supportate.

vector_column

Colonna da utilizzare per creare l'indice vettoriale. Deve essere di tipo vector .

METRICO

Stringa con il nome della metrica della distanza da usare per calcolare la distanza tra i due vettori specificati. Sono supportate le metriche di distanza seguenti:

• cosine - Distanza coseno
• euclidean - Distanza euclidea
• dot - (Negativo) Prodotto punto

TYPE

Tipo di algoritmo ANN utilizzato per compilare l'indice. Attualmente è supportato solo DiskANN. DiskANN è il valore predefinito.

MAXDOP

Esegue l'override dell'opzione di configurazione massimo grado di parallelismo per l'operazione sull'indice. Per altre informazioni, vedere configurazione del server : max degree of parallelism. Usare MAXDOP per limitare il grado di parallelismo e il consumo di risorse risultante per un'operazione di compilazione dell'indice.

max_degree_of_parallelism può essere:

• 1

  Disattiva la generazione di piani paralleli.

• >1

  Limita il grado massimo di parallelismo usato in un'operazione di indice parallelo al numero specificato o meno in base al carico di lavoro di sistema corrente.

• 0 (impostazione predefinita)

  Usa il grado di parallelismo specificato a livello di server, database o gruppo del carico di lavoro, a meno che non venga ridotto in base al carico di lavoro di sistema corrente.

  Per altre informazioni, vedere Configurare le operazioni parallele sugli indici.

  Le operazioni parallele sugli indici non sono disponibili in tutte le edizioni di SQL Server. Per un elenco delle funzionalità supportate dalle edizioni di SQL Server, vedi Edizioni e funzionalità supportate di SQL Server 2025.

Aggiornare gli indici vettoriali alla versione più recente

Gli indici vettoriali appena creati usano automaticamente la struttura dei dati più recente, che fornisce:

• Supporto DML completo: rimuove la limitazione precedente che ha reso le tabelle indicizzate da vettori di sola lettura dopo la creazione dell'indice. Ora puoi eseguire INSERT, UPDATE, DELETE, e MERGE operazioni mantenendo la funzionalità dell'indice vettoriale con una manutenzione automatica e in tempo reale dell'indice.
• Filtraggio iterativo: applica i predicati nella WHERE clausola durante il processo di ricerca vettoriale, non dopo il recupero.
• Ottimizzatore guidato: L'ottimizzatore delle query determina automaticamente se utilizzare l'indice DiskANN o la ricerca kNN in base alle caratteristiche della query.
• Quantizzazione avanzata: Integra tecniche di quantizzazione vettoriale per fornire una migliore efficienza di archiviazione e prestazioni di query più rapide. Queste ottimizzazioni sono trasparenti per gli utenti.

Per dettagli sulle limitazioni precedenti delle versioni degli indici vettoriali, vedi la sezione Limitazioni e considerazioni.

Migrazione da versioni precedenti dell'indice vettoriale

Per abilitare le funzionalità più recenti, devi rilasciare e ricreare indici vettoriali che utilizzano una versione precedente. Questa sezione illustra come identificare, eseguire la migrazione e verificare le versioni dell'indice vettoriale.

Passaggio 1: Identificare gli indici vettoriali esistenti

Usare la query seguente per identificare gli indici vettoriali che richiedono la migrazione:

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;

Come interpretare i risultati

Usa la versione più recente

• Supporta già il filtraggio iterativo, il pieno supporto DML, l'esecuzione guidata dall'ottimizzatore e la quantizzazione migliorata.
• Non è richiesta alcuna migrazione.

Creato con una versione precedente

• Utilizza il comportamento post-filtro legacy.
• Non supporta le ultime funzionalità di ricerca vettoriale.
• La migrazione è fortemente raccomandata per garantire la compatibilità futura.

Passaggio 2: Eliminare e ricreare l'indice vettoriale

Non puoi aggiornare indici vettoriali che usano un formato precedente. Per abilitare le funzionalità diskANN più recenti, eliminare e ricreare l'indice.

Eliminare l'indice esistente

DROP INDEX vec_idx ON dbo.wikipedia_articles;

Ricreare l'indice

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

Passaggio 3: Verificare la versione dell'indice

Dopo aver ricreato l'indice, verifica che stia usando l'ultima versione:

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 colonna deve essere visualizzata 3 per la versione più recente.

Comportamento degli errori con incompatibilità della versione

Se si tenta di usare il TOP_N parametro in VECTOR_SEARCH con un indice vettore di versione più recente, SQL Server restituisce l'errore seguente:

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

Per risolvere questo errore, rimuovere il TOP_N parametro da VECTOR_SEARCH e usare invece la SELECT TOP (N) WITH APPROXIMATE sintassi . Per informazioni dettagliate, vedere Errore con la sintassi legacy.

Limitazioni e considerazioni

Limitazioni della versione dell'indice vettoriale precedente

Le versioni precedenti con indice vettoriale presentano le seguenti limitazioni. Per controllare la versione dell'indice, vedere Verificare la versione dell'indice.

• Solo dopo il filtraggio: i predicati si applicano solo dopo il recupero del vettorio, non durante il processo di ricerca. Questo comportamento può portare a meno righe del previsto quando applichi i filtri.

• Tabelle di sola lettura: le tabelle con indici vettoriali sono di sola lettura. Non puoi eseguire operazioni DML (INSERT, UPDATE, DELETE, MERGE) dopo aver creato l'indice vettoriale. Usare la ALLOW_STALE_VECTOR_INDEX configurazione con ambito database per abilitare le operazioni DML se è possibile tollerare risultati di ricerca non aggiornati.

• Regolazione manuale TOP_N: Devi regolare manualmente il TOP_N parametro per VECTOR_SEARCH compensare il post-filtraggio. Spesso servono valori sovradimensionati per ottenere il numero desiderato di risultati.

Limitazioni correnti (si applica anche alla versione più recente)

L'anteprima corrente presenta le limitazioni seguenti:

• Non puoi partizionare gli indici vettoriali.

• La tabella deve avere un indice raggruppato con chiave primaria su una colonna int .

• Gli indici vettoriali non vengono replicati nei sottoscrittori.

• Non puoi troncare le tabelle con indici vettoriali usando TRUNCATE TABLE. Per rimuovere tutti i dati, eliminare prima l'indice vettoriale, troncare la tabella, ripopolare con almeno 100 righe, quindi ricreare l'indice. Per maggiori informazioni, vedi TRUNCATE TABLE restrizioni.

• Gli indici vettoriali non possono essere distribuiti con DacPac. Puoi distribuire database che contengono indici vettoriali con BACPAC a partire dalla versione 170.5.96 di DacFx. Gli indici vettoriali vengono creati dopo il caricamento dei dati della tabella e la tabella indicizzata deve contenere almeno 100 righe con valori nonNULL vettoriali.

  Durante una distribuzione DACPAC solo schema, la distribuzione può avere successo senza creare l'indice vettoriale se la tabella target contiene meno di 100 righe con valori nonNULL vettoriali. DacFx non crea automaticamente l'indice saltato quando le righe vengono aggiunte successivamente. Dopo aver caricato almeno 100 righe qualificante, creare l'indice vettoriale usando uno script post-deployment, pubblicando nuovamente il DACPAC o eseguendo CREATE VECTOR INDEX.

  Dopo un'importazione o un deployment, verifica che l'indice vettoriale sia stato creato interrogando sys.vector_indexes.

  Come soluzione alternativa prima di DacFx versione 170.5.96, si elimina gli indici vettoriali prima di esportare il database e si ricrea gli indici dopo l'importazione.

Requisiti minimi dei dati

Gli indici vettoriali richiedono un numero minimo di righe con valori nonNULL vettoriali prima di poter creare l'indice.

• Numero minimo di righe: La tabella deve avere almeno 100 righe con valori nonNULL vettoriali.
• Comportamento dell'errore: Se provi a creare un indice vettoriale su una tabella con meno di 100 righe, l'operazione fallisce e restituisce l'errore Msg 42266.

errore di esempio:

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.

Procedura consigliata: popolare la tabella con almeno 100 righe prima di creare l'indice vettoriale. Per scenari di sviluppo e test in cui servono meno righe, VECTOR_SEARCH funziona senza indice usando un approccio di scansione bruta. Tuttavia, questo metodo degrada le prestazioni con dataset più grandi.

Supporto DML

Quando crei un indice vettoriale DiskANN usando l'ultima versione, la tabella non è più in sola lettura. Puoi modificare i dati utilizzando operazioni standard di manipolazione dei dati (DML), e le modifiche appaiono automaticamente nei risultati della ricerca vettoriale.

Questa funzionalità rende la ricerca vettoriale adatta per carichi di lavoro live e transazionali in cui i dati cambiano nel tempo.

Note sul comportamento

• Le operazioni DML non richiedono l'eliminazione o la ricompilazione dell'indice vettoriale.
• Le modifiche sono visibili alle query di ricerca vettoriali dopo il commit della transazione.
• Per la sostituzione dei dati su larga scala,ad esempio eliminando la maggior parte delle righe e inserendo un set completamente nuovo di incorporamenti, è consigliabile eliminare e ricreare l'indice vettoriale dopo il caricamento dei dati per garantire una qualità ottimale della ricerca.

Monitoraggio della manutenzione dell'indice vettoriale

Gli indici vettoriali eseguono la manutenzione in background per incorporare le modifiche DML. Usare la sys.dm_db_vector_indexes visualizzazione a gestione dinamica per monitorare lo stato dell'attività di manutenzione e integrità dell'indice.

Combinazione di indici vettoriali con indici tradizionali

Gli indici vettoriali funzionano insieme agli indici di albero B tradizionali per garantire prestazioni ottimali delle query. Quando si usa il filtro iterativo con VECTOR_SEARCH, è consigliabile creare indici tradizionali sulle colonne usate nei predicati di filtro.

Per informazioni dettagliate sul comportamento di filtro iterativo e sulle differenze rispetto alle versioni precedenti, vedere Comportamento di filtro iterativo.

Scenario di esempio:

-- 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);

Vantaggi delle prestazioni:

Quando si eseguono query con filtro iterativo, Query Optimizer di SQL Server usa entrambi i tipi di indice:

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;

In questa query:

• L'indice vettoriale identifica incorporamenti simili in base al vettore di query
• Indice tradizionale sui (category) filtri candidati in modo efficiente durante il processo di ricerca iterativo

Questa strategia composita può migliorare significativamente le prestazioni delle query rispetto all'uso di un solo indice vettoriale, in particolare quando i predicati di filtro hanno una selettività elevata.

Indicazioni sulla qualità dei dati e sulla manutenzione per gli indici vettoriali

Evitare set di dati con incorporamenti duplicati elevati

L'indicizzazione vettoriale funziona meglio quando gli incorporamenti rappresentano contenuto semantico diversificato. Non usare dataset con una proporzione elevata di vettori duplicati per l'indicizzazione vettoriale.

La duplicazione elevata può portare a:

• Qualità scarsa dei risultati: i vettori duplicati vengono visualizzati ripetutamente nei risultati, affollando le corrispondenze semantiche più rilevanti.
• Efficacia ridotta: gli incorporamenti duplicati spostano i vicini migliori, riducendo l'utilità della ricerca di somiglianza.
• Utilizzo delle risorse non necessario: gli indici vettoriali sono costosi da compilare e gestire e i duplicati aggiungono costi senza aggiungere valore.

Procedura consigliata: deduplicare gli incorporamenti prima di creare un indice vettoriale per migliorare sia le prestazioni che la qualità dei risultati.

Scenari di sostituzione dei dati su larga scala

Gli indici vettoriali supportano inserimenti, aggiornamenti ed eliminazioni. Tuttavia, quando si sostituiscono la maggior parte o tutti gli embedding—ad esempio, re-embedding di un dataset con un nuovo modello—l'indice esistente potrebbe non riflettere più la nuova distribuzione dei dati.

Negli scenari di sostituzione su larga scala:

• Le query di ricerca vettoriale continuano a restituire risultati validi.
• La qualità del richiamo e del ranking potrebbe degradarsi, perché la struttura dell'indice è stata costruita per una distribuzione di embedding diversa.

Procedura consigliata: quando si esegue la sostituzione dei dati quasi completa (eliminazione e inserimento di incorporamenti aggiornati), eliminare e ricreare l'indice vettoriale dopo il caricamento dei nuovi dati. La ricreazione dell'indice garantisce che sia ottimizzata per la nuova distribuzione di incorporamento e ripristina il comportamento prevedibile delle query.

Problemi noti

Per altre informazioni, vedere Problemi noti.

Autorizzazioni

Serve ALTER il permesso sul tavolo.

Esempi

Scaricare e importare l'articolo di Wikipedia con esempi di incorporamenti vettoriali .

Questi esempi suppongono una tabella chiamata wikipedia_articles con una colonna title_vector di caratteri vector che memorizza le inserzioni dei titoli degli articoli di Wikipedia. Utilizza title_vector un modello di embedding come text-embedding-ada-002 o text-embedding-3-small, che restituisce vettori con 1.536 dimensioni.

Per altri esempi, incluse soluzioni end-to-end, consulta il repository database SQL di Azure Vector Search Samples su GitHub.

Esempio 1

Nell'esempio seguente viene creato un indice vettoriale nella title_vector colonna usando la cosine metrica .

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

Esempio 2

Il seguente esempio crea un indice vettoriale sulla title_vector colonna usando la metrica prodotto (negativo dot ). Limita il parallelismo a 8 e memorizza il vettore nel SECONDARY file group.

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

Esempio 3

Questo esempio utilizza CREATE VECTOR INDEX e la funzione correlata VECTOR_SEARCH . Gli incorporamenti vengono fittizi. In uno scenario reale, genera embedding utilizzando un modello di embedding e AI_GENERATE_EMBEDDINGS, oppure una libreria esterna come OpenAI SDK.

Il blocco di codice seguente illustra CREATE VECTOR INDEX con incorporamenti fittizi:

1. Abilita la funzione di anteprima (richiesta solo per SQL Server 2025; non necessaria per database SQL di Azure o SQL Database in Fabric).
2. Creare una tabella di esempio con una colonna con tipo di dati vector(5).Create a sample table dbo.Articles with a column embedding with data type vector(5).
3. Inserire 100 righe di dati di esempio con dati fittizi di incorporamento.
4. Creare un indice vettoriale in dbo.Articles.embedding.
5. Illustrare la ricerca di somiglianza del vettore con la VECTOR_SEARCH funzione .

-- 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 sintassi per l'esecuzione di query dipende dalla versione dell'indice vettoriale:

Per gli indici di versione precedenti (sintassi deprecata):

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;

Esempio 4: Uso delle operazioni DML

I seguenti esempi dimostrano operazioni DML su una tabella con un indice vettoriale creato utilizzando l'ultima versione.

Elimina righe

L'eliminazione di righe li rimuove dai risultati della ricerca di tabella e vettoriale.

DELETE FROM dbo.wikipedia_articles
WHERE id = 12345;

Dopo la fine dell'operazione di cancellazione, la riga rimossa non appare più nelle query di ricerca vettoriale.

Inserisci nuove righe

È possibile inserire nuove righe con incorporamenti e diventano immediatamente ricercabili senza ricompilare l'indice.

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)
);

Gli incorporamenti appena inseriti vengono incorporati automaticamente nell'indice vettoriale e possono essere restituiti dalle query di ricerca vettoriali successive.

Aggiornare le righe esistenti

L'aggiornamento di colonne vettoriali o non vettoriali è completamente supportato.

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;

Se aggiorni una colonna vettoriale, l'indice si aggiorna di conseguenza, quindi le future ricerche vettoriali utilizzano il nuovo embedding.

Utilizzo MERGE per operazioni complesse

L'istruzione MERGE consente di eseguire operazioni di inserimento, aggiornamento ed eliminazione in un'unica istruzione.

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'indice vettoriale si aggiorna automaticamente per riflettere tutte le modifiche apportate dall'affermazione MERGE .

Contenuti correlati

• Ricerca vettoriale e indici vettoriali nel motore di database SQL
• tipo di dati vettoriale
• VECTOR_SEARCH (Transact-SQL)
• sys.vector_indexes (Transact-SQL)
• sys.dm_db_vector_indexes (Transact-SQL)
• Esempi di ricerca vettoriale del database SQL di Azure