CREATE VECTOR INDEX (Transact-SQL)

Aplica-se a: SQL Server 2025 (17.x) Base de Dados SQL do AzureAzure SQL Managed InstanceSQL database in Microsoft Fabric

Crie um índice aproximado numa coluna vetorial para melhorar o desempenho das pesquisas de vizinhos mais próximos. Para saber mais sobre como funcionam a indexação vetorial e a pesquisa vetorial, e as diferenças entre pesquisa exata e aproximada, consulte Pesquisa vetorial e índices vetoriais no SQL Database Engine.

Disponibilidade de funcionalidades

• Vector index e VECTOR_SEARCH estão geralmente disponíveis (GA) em Base de Dados SQL do Azure, base de dados SQL em Microsoft Fabric e Azure SQL Managed Instance com a política de atualizaçãoAlways-up-to-date.
• Vector index e VECTOR_SEARCH são funcionalidades de pré-visualização no SQL Server 2025 (17.x) e no Azure SQL Managed Instance com a política de atualização do SQL Server 2025.

Funcionalidade de pré-visualização do SQL Server 2025

No SQL Server 2025 e no Azure SQL Managed Instance, na política de atualizaçãodo SQL Server 2025, os índices vetoriais e a VECTOR_SEARCH função estão em pré-visualização e sujeitos a alterações. Para usar esta funcionalidade, deve ativar a PREVIEW_FEATURESconfiguração com âmbito de base de dados.

Verifique as limitações atuais antes de o usar.

Sintaxe

Transact-SQL convenções de sintaxe

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" } ]
[;]

Argumentos

index_name

O nome do índice. Os nomes de índice devem ser exclusivos dentro de uma tabela, mas não precisam ser exclusivos dentro de um banco de dados. Os nomes dos índices devem seguir as regras dos identificadores.

objeto

Tabela na qual o índice é criado. Deve ser uma tabela de base. Não há suporte para visualizações, tabelas temporárias, locais e globais.

vector_column

Coluna a ser usada para criar o índice vetorial. Deve ser do tipo vetorial .

MÉTRICA

Uma cadeia de caracteres com o nome da métrica de distância a ser usada para calcular a distância entre os dois vetores fornecidos. As seguintes métricas de distância são suportadas:

• cosine - Distância cossena
• euclidean - Distância euclidiana
• dot - Produto Dot (Negativo)

TYPE

O tipo de algoritmo ANN usado para construir o índice. Atualmente, apenas DiskANN é suportado. DiskANN é o valor padrão.

MAXDOP

Substitui o grau máximo de paralelismo opção de configuração para a operação de índice. Para obter mais informações, consulte Configuração do servidor : grau máximo de paralelismo. Use MAXDOP para limitar o grau de paralelismo e o consumo de recursos resultante para uma operação de compilação de índice.

max_degree_of_parallelism pode ser:

• 1

  Suprime a geração de planos paralelos.

• >1

  Restringe o grau máximo de paralelismo usado em uma operação de índice paralelo ao número especificado ou menos com base na carga de trabalho atual do sistema.

• 0 (padrão)

  Usa o grau de paralelismo especificado no nível do servidor, banco de dados ou grupo de carga de trabalho, a menos que seja reduzido com base na carga de trabalho atual do sistema.

  Para obter mais informações, consulte Configurar operações de índice paralelo.

  As operações de índice paralelo não estão disponíveis em todas as edições do SQL Server. Para uma lista de funcionalidades suportadas pelas edições do SQL Server, consulte Edições e funcionalidades suportadas do SQL Server 2025.

Atualizar os índices vetoriais para a versão mais recente

Os índices vetoriais recém-criados utilizam automaticamente a estrutura de dados mais recente, que fornece:

• Suporte total para DML: Remove a limitação anterior que tornava as tabelas indexadas vetorialmente apenas leitura após a criação do índice. Agora pode realizar INSERT, UPDATE, DELETE, e MERGE operações mantendo a funcionalidade do índice vetorial com manutenção automática e em tempo real do índice.
• Filtragem iterativa: Aplica os predicados na WHERE cláusula durante o processo de pesquisa vetorial, não após a recuperação.
• Orientado pelo otimizador: O otimizador de consultas determina automaticamente se deve usar o índice DiskANN ou a pesquisa kNN com base nas características da consulta.
• Quantização avançada: Integra técnicas de quantização vetorial para proporcionar melhor eficiência de armazenamento e desempenho de consulta mais rápido. Estas otimizações são transparentes para os utilizadores.

Para detalhes sobre as limitações anteriores das versões de índices vetoriais, consulte a secção Limitações e considerações.

Migração de versões anteriores de índice vetorial

Para ativar as funcionalidades mais recentes, deve eliminar e recriar índices vetoriais que utilizam uma versão anterior. Esta secção explica como identificar, migrar e verificar versões do índice vetorial.

Passo 1: Identificar índices vetoriais existentes

Use a seguinte consulta para identificar índices vetoriais que requerem migração:

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;

Como interpretar os resultados

Utiliza a versão mais recente

• Já suporta filtragem iterativa, suporte completo a DML, execução orientada por otimizadores e quantização melhorada.
• Não é necessária migração.

Criado usando uma versão anterior

• Usa comportamento pós-filtro antigo.
• Não suporta as capacidades mais recentes de pesquisa vetorial.
• A migração é fortemente recomendada para garantir compatibilidade futura.

Passo 2: Retirar e recriar o índice vetorial

Não podes atualizar índices vetoriais que usam um formato anterior. Para ativar as capacidades mais recentes do DiskANN, desfaça e recrie o índice.

Eliminar o índice existente

DROP INDEX vec_idx ON dbo.wikipedia_articles;

Recriar o índice

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

Passo 3: Verificar a versão indexada

Depois de recriares o índice, verifica se está a usar a versão mais 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';

A index_version coluna deve mostrar 3 a versão mais recente.

Comportamento de erro com incompatibilidade de versões

Se tentar usar o TOP_N parâmetro em VECTOR_SEARCH com um índice vetorial da versão mais recente, o SQL Server devolve o seguinte erro:

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

Para resolver este erro, remova o TOP_N parâmetro de VECTOR_SEARCH e use a SELECT TOP (N) WITH APPROXIMATE sintaxe em vez disso. Para informações detalhadas, veja Erro usando sintaxe legada.

Limitações e considerações

Limitações anteriores das versões do índice vetorial

Versões anteriores de índice vetorial apresentam as seguintes limitações. Para verificar a sua versão indexada, consulte Verificar a versão indexada.

• Apenas após filtragem: Os predicados aplicam-se apenas após a recuperação vetorial, não durante o processo de pesquisa. Este comportamento pode resultar em menos linhas do que o esperado quando aplicas filtros.

• Tabelas somente de leitura: Tabelas com índices vetoriais são apenas de leitura. Não pode realizar operações DML (INSERT, UPDATE, DELETE, MERGE) depois de criar o índice vetorial. Use a ALLOW_STALE_VECTOR_INDEX configuração com escopo da base de dados para permitir operações DML se conseguir tolerar resultados de pesquisa obsoletos.

• Afinação manual TOP_N: Deve ajustar manualmente o TOP_N parâmetro para VECTOR_SEARCH compensar o pós-filtragem. Muitas vezes são necessários valores sobredimensionados para obter o número desejado de resultados.

Limitações atuais (aplica-se também à versão mais recente)

A visualização atual tem as seguintes limitações:

• Não se podem particionar índices vetoriais.

• A tabela deve ter um índice agrupado com chave primária numa coluna int .

• Os índices vetoriais não são replicados para assinantes.

• Não pode truncar tabelas com índices vetoriais usando TRUNCATE TABLE. Para remover todos os dados, retire primeiro o índice vetorial, trunque a tabela, repreenche com pelo menos 100 linhas e depois recrie o índice. Para mais informações, consulte TRUNCATE TABLE restrições.

• Índices vetoriais não podem ser implementados com o DacPac. Pode implementar bases de dados que contenham índices vetoriais com BACPAC a partir da versão 170.5.96 do DacFx. Os índices vetoriais são criados após o carregamento dos dados da tabela, e a tabela indexada deve conter pelo menos 100 linhas com valores nãoNULL vetoriais.

  Durante uma implementação DACPAC apenas com esquema, a implementação pode ter sucesso sem criar o índice vetorial se a tabela alvo contiver menos de 100 linhas com valores nãoNULL vetoriais. O DacFx não cria automaticamente o índice saltado quando as linhas são adicionadas mais tarde. Depois de carregar pelo menos 100 linhas qualificadas, crie o índice vetorial usando um script pós-implementação, publicando novamente o DACPAC ou executando CREATE VECTOR INDEX.

  Após uma importação ou implementação, verifique se o índice vetorial foi criado consultando sys.vector_indexes.

  Como solução alternativa antes da versão 170.5.96 do DacFx, retirar os índices vetoriais antes de exportar a base de dados e recriar os índices após a importação.

Requisitos mínimos de dados

Índices vetoriais exigem um número mínimo de linhas com valores nãoNULL vetoriais antes de poder criar o índice.

• Contagem mínima de linhas: A tabela deve ter pelo menos 100 linhas com valores nãoNULL vetoriais.
• Comportamento de erro: Se tentar criar um índice vetorial numa tabela com menos de 100 linhas, a operação falha e devolve o erro Msg 42266.

Exemplo de erro:

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.

Boa prática: Preenche a tabela com pelo menos 100 linhas antes de criar o índice vetorial. Para cenários de desenvolvimento e testes onde precisas de menos linhas, VECTOR_SEARCH funciona sem índice usando uma abordagem de varrimento por força bruta. No entanto, este método degrada o desempenho com conjuntos de dados maiores.

Suporte DML

Quando cria um índice vetorial DiskANN usando a versão mais recente, a tabela deixa de ser apenas de leitura. Pode modificar dados usando operações padrão de manipulação de dados (DML), e as alterações aparecem automaticamente nos resultados da pesquisa vetorial.

Esta capacidade torna a pesquisa vetorial adequada para cargas de trabalho transacionais em tempo real, onde os dados mudam ao longo do tempo.

Notas de comportamento

• As operações DML não exigem eliminar ou reconstruir o índice vetorial.
• As alterações são visíveis nas consultas de pesquisa vetorial após o commit da transação.
• Para substituição de dados em grande escala (por exemplo, eliminar a maioria das linhas e inserir um conjunto totalmente novo de embeddings), considere eliminar e recriar o índice vetorial após a carga dos dados para garantir uma qualidade de pesquisa ótima.

Monitorização da manutenção do índice vetorial

Os índices vetoriais realizam manutenção em segundo plano para incorporar as alterações do DML. Use a vista dinâmica de gestão sys.dm_db_vector_indexes para monitorizar o estado de saúde do índice e o estado da tarefa de manutenção.

Combinação de índices vetoriais com índices tradicionais

Os índices vetoriais funcionam em conjunto com os índices tradicionais da árvore B para proporcionar um desempenho ótimo de consulta. Ao usar filtragem iterativa com VECTOR_SEARCH, considere criar índices tradicionais em colunas usadas em predicados de filtro.

Para informações detalhadas sobre o comportamento de filtragem iterativa e como difere das versões anteriores, veja Comportamento de filtragem iterativa.

Exemplo de cenário:

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

Benefício de desempenho:

Ao executar consultas com filtragem iterativa, o otimizador de consultas do SQL Server utiliza ambos os tipos de índice:

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;

Nesta consulta:

• O índice vetorial identifica embeddings semelhantes com base no vetor de consulta
• O índice tradicional filtra (category) os candidatos de forma eficiente durante o processo de pesquisa iterativa

Esta estratégia composta pode melhorar significativamente o desempenho da consulta em comparação com a utilização apenas de um índice vetorial, especialmente quando os predicados de filtro têm alta seletividade.

Orientações de qualidade e manutenção de dados para índices vetoriais

Evite conjuntos de dados com elevadas incorporações duplicadas

A indexação vetorial funciona melhor quando os embeddings representam conteúdo semântico diversificado. Não uses conjuntos de dados com uma elevada proporção de vetores duplicados para indexação vetorial.

Uma elevada duplicação pode levar a:

• Má qualidade dos resultados: Vetores duplicados aparecem repetidamente nos resultados, afastando correspondências semânticas mais relevantes.
• Eficácia reduzida: Embeddings duplicados deslocam vizinhos melhores, diminuindo a utilidade da pesquisa por similaridade.
• Uso desnecessário de recursos: Índices vetoriais são caros de construir e manter, e duplicados acrescentam custo sem acrescentar valor.

Boa prática: Deduplicar embeddings antes de criar um índice vetorial para melhorar tanto o desempenho como a qualidade dos resultados.

Cenários de substituição de dados em grande escala

Os índices vetoriais suportam inserções, atualizações e eliminações. No entanto, quando substitui a maioria ou todos os embeddings — por exemplo, reincorporar um conjunto de dados com um novo modelo — o índice existente pode deixar de refletir a nova distribuição de dados.

Em cenários de substituição em grande escala:

• As consultas de pesquisa vetorial continuam a devolver resultados válidos.
• A qualidade da recordação e do ranking pode degradar-se, porque a estrutura do índice foi construída para uma distribuição de embedding diferente.

Boa prática: Ao realizar a substituição quase completa dos dados (eliminar e inserir novos embeddings), retirar e recriar o índice vetorial após carregar os novos dados. Recriar o índice garante que está otimizado para a nova distribuição de embedding e restaura o comportamento previsível das consultas.

Problemas conhecidos

Para obter mais informações, consulte Problemas conhecidos.

Permissões

Precisas ALTER de permissão na mesa.

Exemplos

Descarregue e importe o artigo da Wikipédia com o exemplo de embeddings vetoriais .

Estes exemplos assumem uma tabela nomeada wikipedia_articles com uma coluna title_vector de tipo vector que armazena os títulos embeddings dos artigos da Wikipédia. Utiliza title_vector um modelo de embedding como text-embedding-ada-002 ou text-embedding-3-small, que devolve vetores com 1.536 dimensões.

Para mais exemplos, incluindo soluções de ponta a ponta, consulte o repositório Base de Dados SQL do Azure Vector Search Samples no GitHub.

Exemplo 1

O exemplo a title_vector seguir cria um índice de vetor na coluna usando a cosine métrica.

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

Exemplo 2

O exemplo seguinte cria um índice vetorial na title_vector coluna usando a métrica do produto (negativo dot ). Limita o paralelismo a 8 e armazena o vetor no SECONDARY grupo de ficheiros.

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

Exemplo 3

Este exemplo utiliza CREATE VECTOR INDEX e a função relacionada VECTOR_SEARCH . As incorporações são ridicularizadas. Num cenário do mundo real, gere embeddings usando um modelo de embedding e AI_GENERATE_EMBEDDINGS, ou utiliza uma biblioteca externa como o OpenAI SDK.

O seguinte bloco de código demonstra CREATE VECTOR INDEX com mock embeddings:

1. Ative a funcionalidade de pré-visualização (necessária apenas para o SQL Server 2025; não necessária para Base de Dados SQL do Azure ou SQL Database no Fabric).
2. Crie uma tabela dbo.Articles de exemplo com uma coluna embedding com o tipo de dados vetor(5).
3. Insira 100 linhas de dados de amostra com dados de embedding mock.
4. Crie um índice vetorial no dbo.Articles.embedding.
5. Demonstrar a pesquisa de semelhança vetorial com a VECTOR_SEARCH função.

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

A sintaxe para a consulta depende da versão do índice vetorial:

Para índices de versões anteriores (sintaxe obsoleta):

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;

Exemplo 4: Trabalhar com operações DML

Os exemplos seguintes demonstram operações DML numa tabela com um índice vetorial criado usando a versão mais recente.

Excluir linhas

Eliminar linhas remove-as tanto da tabela como dos resultados de pesquisa vetorial.

DELETE FROM dbo.wikipedia_articles
WHERE id = 12345;

Após a operação de eliminação terminar, a linha removida deixa de aparecer nas consultas de pesquisa vetorial.

Inserir novas linhas

Podes inserir novas linhas com embeddings, e tornam-se imediatamente pesquisáveis sem teres de reconstruir o índice.

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

As incorporações recém-inseridas são automaticamente incorporadas no índice vetorial e podem ser devolvidas por consultas vetoriais subsequentes.

Atualizar linhas existentes

A atualização de colunas vetoriais ou não vetoriais é totalmente suportada.

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 atualizares uma coluna vetorial, o índice atualiza-se em conformidade, por isso futuras pesquisas vetoriais usam a nova incorporação.

Utilização MERGE para operações complexas

A MERGE instrução permite-lhe realizar operações de inserção, atualização e eliminação numa única instrução.

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;

O índice vetorial atualiza-se automaticamente para refletir todas as alterações feitas pela MERGE declaração.

Conteúdo relacionado

• Pesquisa vetorial e índices vetoriais no Mecanismo de Banco de Dados SQL
• Tipo de dados vetoriais
• VETOR_SEARCH (Transact-SQL)
• sys.vetor_indexes (Transact-SQL)
• sys.dm_db_vector_indexes (Transact-SQL)
• Exemplos de pesquisa vetorial do Banco de Dados SQL do Azure