CREA INDICE VETTORIALE (Transact-SQL) (Anteprima)

Si applica a: SQL Server 2025 (17.x) Azure SQL DatabaseSQL database in Microsoft Fabric

Creare un indice approssimativo su una colonna vettoriale per migliorare le prestazioni della ricerca dei vicini più vicini. Per altre informazioni sul funzionamento dell'indicizzazione vettoriale e della ricerca vettoriale e sulle differenze tra ricerca esatta e approssimativa, vedere Ricerca vettoriale e indici vettoriali nel motore di database SQL.

Database SQL di Azure e database SQL in Fabric

La funzione è in anteprima. Prima di procedere, controllare le limitazioni e le considerazioni .

Disponibilità regionale

Questa funzionalità viene distribuita nel database SQL di Azure e nel database SQL in Microsoft Fabric. Durante l'implementazione, la disponibilità e il comportamento possono variare in base all'area e alla versione dell'indice. Se una funzionalità o una sintassi non è disponibile, diventa disponibile automaticamente al termine della distribuzione. Per lo stato di disponibilità a livello di area corrente, vedere Disponibilità delle funzionalità in base all'area.

Funzionalità di anteprima di SQL Server 2025

In SQL Server 2025 questa funzione è in anteprima ed è soggetta a modifiche. Per usare questa funzionalità, è necessario abilitare la PREVIEW_FEATURESconfigurazione con ambito database.

Assicurarsi di controllare le limitazioni correnti 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.

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 possibile eseguire operazioni INSERT, UPDATE, DELETE e MERGE mantenendo la funzionalità dell'indice vettoriale con la manutenzione automatica e in tempo reale degli indici
• Filtro iterativo: i predicati nella clausola WHERE vengono applicati durante il processo di ricerca vettoriale, non dopo il recupero
• Ottimizzatore: Query Optimizer determina automaticamente se usare l'indice DiskANN o la ricerca kNN in base alle caratteristiche delle query
• Quantizzazione avanzata: le tecniche di quantizzazione vettoriale sono state integrate per garantire una migliore efficienza di archiviazione e prestazioni delle query più veloci, con queste ottimizzazioni trasparenti per gli utenti

Per informazioni dettagliate sulle limitazioni della versione dell'indice vettoriale precedente, vedere la sezione Limitazioni e considerazioni.

Migrazione da versioni precedenti dell'indice vettoriale

Gli indici vettoriali creati con una versione precedente devono essere eliminati e ricreati per abilitare le funzionalità più recenti. 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 filtro iterativo, il supporto DML completo, l'esecuzione basata su optimizer e la quantizzazione migliorata
• Nessuna migrazione necessaria

Creato con una versione precedente

• Usa il comportamento di post-filtro legacy
• Non supporta le funzionalità di ricerca vettoriale più recenti
• La migrazione è fortemente consigliata per garantire la compatibilità futura

Passaggio 2: Eliminare e ricreare l'indice vettoriale

Gli indici vettoriali creati con un formato precedente non possono essere aggiornati sul posto. 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 la ricreazione, verificare che l'indice usi la versione più recente:

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 dell'indice vettoriale presentano le limitazioni aggiuntive seguenti. Per controllare la versione dell'indice, vedere Verificare la versione dell'indice.

• Solo post-filtro: i predicati vengono applicati solo dopo il recupero del vettore, non durante il processo di ricerca. Ciò può comportare un minor numero di righe restituite del previsto quando vengono applicati filtri.

• Tabelle di sola lettura: le tabelle con indici vettoriali sono di sola lettura. Non sono consentite operazioni DML (INSERT, UPDATE, DELETE, MERGE) dopo la creazione dell'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.

• Ottimizzazione manuale TOP_N: è necessario modificare manualmente il parametro in VECTOR_SEARCH per compensare il TOP_N post-filtro, spesso richiedendo 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:

• Gli indici vettoriali non possono essere partizionati. Nessun supporto per la partizione.

• La tabella deve avere un indice cluster con chiave primaria.

• Gli indici vettoriali non vengono replicati nei sottoscrittori.

• Le tabelle con indici vettoriali non possono essere troncate tramite 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 altre informazioni, vedere RESTRIZIONI TRUNCATE TABLE.

Requisiti minimi dei dati

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

• Numero minimo di righe: nella tabella devono essere presenti almeno 100 righe con valori vettoriali non NULL.
• Comportamento errore: il tentativo di creare un indice vettoriale in una tabella con meno di 100 righe ha esito negativo con 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 sono necessarie meno righe, VECTOR_SEARCH funziona senza un indice usando un approccio di analisi di forza bruta, anche se le prestazioni diminuiscono con set di dati più grandi.

Supporto DML

Dopo aver creato un indice vettoriale DiskANN usando la versione più recente, la tabella non è più di sola lettura. È possibile modificare liberamente i dati usando operazioni DML (Data Manipulation Language) standard e le modifiche vengono riflesse 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. I set di dati con una percentuale elevata di vettori duplicati non sono consigliati 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 la maggior parte o tutte le incorporazioni vengono sostituite, ad esempio ricreando un set di dati 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 vettoriali continuano a restituire risultati validi
• Tuttavia, la qualità di richiamo e classificazione può peggiorare, perché la struttura dell'indice è stata compilata per una distribuzione di incorporamento 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

L'utente deve disporre ALTER dell'autorizzazione per la tabella.

Esempi

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

Gli esempi presuppongono l'esistenza di una tabella denominata wikipedia_articles con una colonna title_vector di tipo vector che archivia gli incorporamenti del titolo degli articoli di Wikipedia. title_vector si presuppone che sia un incorporamento generato con un modello di incorporamento come text-embedding-ada-002 o text-embedding-3-small, che restituisce vettori con 1.536 dimensioni.

Per altri esempi, incluse le soluzioni end-to-end, vedere il repository GitHub Degli esempi di ricerca vettoriale del database SQL di Azure.

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

Nell'esempio seguente viene creato un indice vettoriale nella title_vector colonna usando la metrica del prodotto (negativo), dot limitando il parallelismo a 8 e archiviando il vettore nel SECONDARY filegroup.

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

Esempio 3

Esempio end-to-end di base che usa CREATE VECTOR INDEX e la funzione correlata VECTOR_SEARCH . Gli incorporamenti vengono fittizi. In uno scenario reale, gli incorporamenti vengono generati usando un modello di incorporamento e AI_GENERATE_EMBEDDINGS o una libreria esterna come OpenAI SDK.

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

1. Abilita la funzionalità di anteprima (necessaria solo per SQL Server 2025, non necessaria per il database SQL di Azure o il database SQL 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 ' + CAST(value AS NVARCHAR(10)),
    'Content for article ' + CAST(value AS NVARCHAR(10)),
    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

Negli esempi seguenti vengono illustrate le operazioni DML in una tabella con un indice vettoriale creato usando la versione più recente.

Elimina righe

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

DELETE FROM dbo.wikipedia_articles
WHERE id = 12345;

Al termine dell'eliminazione, la riga rimossa non viene più visualizzata nelle query di ricerca vettoriali.

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 viene aggiornata una colonna vettoriale, l'indice viene aggiornato di conseguenza in modo che le ricerche vettoriali future usino il nuovo incorporamento.

Usare 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 viene aggiornato automaticamente in modo da riflettere tutte le modifiche apportate dall'istruzione MERGE .

Contenuti correlati

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