CREATE VECTOR INDEX (Transact-SQL)

Aplica-se a: SQL Server 2025 (17.x) Banco de Dados SQL do AzureInstância Gerenciada de SQL do Azurebanco de dados SQL no Microsoft Fabric

Crie um índice aproximado em uma coluna vetorial para melhorar o desempenho das buscas de vizinhos mais próximos. Para saber mais sobre como funcionam a indexação vetorial e a busca vetorial, e as diferenças entre busca exata e aproximada, veja Busca vetorial e indexes vetoriais no SQL Mecanismo de Banco de Dados.

Disponibilidade de funcionalidades

• O índice vetorial e VECTOR_SEARCH geralmente está disponível (GA) em Banco de Dados SQL do Azure, banco de dados SQL em Microsoft Fabric e Instância Gerenciada de SQL do Azure com a política de atualizaçãode data Always-up-to.
• Índice vetorial e VECTOR_SEARCH são recursos de pré-visualização no SQL Server 2025 (17.x) e no Instância Gerenciada de SQL do Azure com a política de atualização do SQL Server 2025.

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

No SQL Server 2025 e no Instância Gerenciada de SQL do Azure na política de atualizaçãodo SQL Server 2025, os índices vetoriais e a VECTOR_SEARCH função estão em prévia e sujeitos a alterações. Para usar esse recurso, você deve ativar a PREVIEW_FEATURESconfiguração com escopo do banco de dados.

Verifique as limitações atuais antes de usá-lo.

Sintaxe

Convenções de sintaxe de 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" } ]
[;]

Argumentos

index_name

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

objeto

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

vector_column

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

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. Há suporte para as seguintes métricas de distância:

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

TYPE

O tipo de algoritmo ANN usado para criar o índice. No momento, há suporte apenas DiskANN. DiskANN é o valor padrão.

MAXDOP

Substitui a opção de configuração de grau máximo de paralelismo 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 build de índice.

max_degree_of_parallelism pode ser:

• 1

  Suprime a geração de plano paralelo.

• >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, do banco de dados ou do 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 paralelas não estão disponíveis em todas as edições do SQL Server. Para uma lista de recursos suportados pelas edições do SQL Server, veja Edições e recursos suportados do SQL Server 2025.

Atualizar índices de vetor para a versão mais recente

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

• Suporte completo ao DML: remove a limitação anterior que tornava as tabelas indexadas por vetor somente leitura após a criação do índice. Agora você 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 busca vetorial, não após a recuperação.
• Otimizador: O otimizador de consultas determina automaticamente se deve usar o índice DiskANN ou a busca 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. Essas otimizações são transparentes para os usuários.

Para detalhes sobre limitações anteriores de versões de índices vetoriais, veja a seção Limitações e considerações.

Migrando de versões de índice de vetor anteriores

Para habilitar as capacidades mais recentes, você deve eliminar e recriar índices vetoriais que usam uma versão anterior. Esta seção explica como identificar, migrar e verificar versões de índice de vetor.

Etapa 1: identificar índices de vetor existentes

Use a consulta a seguir para identificar índices vetoriais que exigem 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

Usa a versão mais recente

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

Criado usando uma versão anterior

• Usa comportamento pós-filtro legado.
• Não suporta as últimas capacidades de busca vetorial.
• A migração é fortemente recomendada para garantir compatibilidade futura.

Etapa 2: Remover e recriar o índice de vetor

Você não pode atualizar índices vetoriais que usam um formato anterior. Para habilitar os recursos mais recentes do DiskANN, remova e recrie o índice.

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

Etapa 3: Verificar a versão do índice

Depois de recriar o índice, verifique se ele está usando 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 ser exibida 3 para a versão mais recente.

Comportamento de erro com incompatibilidade de versão

Se você tentar usar o TOP_N parâmetro VECTOR_SEARCH com um índice de vetor de versão mais recente, o SQL Server retornará o seguinte erro:

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

Para resolver esse erro, remova o TOP_N parâmetro VECTOR_SEARCH e use a SELECT TOP (N) WITH APPROXIMATE sintaxe. Para obter informações detalhadas, consulte Erro usando a sintaxe herdada.

Limitações e considerações

Limitações anteriores da versão do índice vetor

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

• Apenas após filtragem: Predicados se aplicam apenas após a recuperação vetorial, não durante o processo de busca. Esse comportamento pode resultar em menos linhas retornadas do que o esperado ao aplicar filtros.

• Tabelas somente leitura: tabelas com índices de vetor são somente leitura. Você não pode realizar operações DML (INSERT, UPDATE, DELETE, MERGE) após criar o índice vetorial. Use a configuração no escopo do ALLOW_STALE_VECTOR_INDEX banco de dados para habilitar operações DML se você puder tolerar resultados de pesquisa obsoletos.

• Ajuste manual TOP_N: Você deve ajustar manualmente o TOP_N parâmetro para VECTOR_SEARCH compensar o pós-filtragem. Frequentemente você precisa de valores superdimensionados para obter o número desejado de resultados.

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

A versão prévia atual tem as seguintes limitações:

• Você não pode particionar índices vetoriais.

• A tabela deve ter um índice agrupado de chaves primárias em uma coluna int .

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

• Você não pode truncar tabelas com índices vetoriais usando TRUNCATE TABLE. Para remover todos os dados, solte o índice de vetor primeiro, trunque a tabela, repovoe com pelo menos 100 linhas e recrie o índice. Para mais informações, vejaTRUNCATE TABLE restrições.

• Índices vetoriais não podem ser implantados com DacPac. Você pode implantar bancos de dados que contenham índices vetoriais com o BACPAC a partir da versão 170.5.96 do DacFx. Í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 implantação DACPAC apenas com esquema, a implantação pode ser bem-sucedida 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 pulado quando as linhas são adicionadas depois. Após carregar pelo menos 100 linhas qualificadas, crie o índice vetorial usando um script pós-implantação, publicando novamente o DACPAC ou executando CREATE VECTOR INDEX.

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

  Como solução alternativa antes do DacFx versão 170.5.96, retirar os índices vetoriais antes de exportar o banco 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 você tentar criar um índice vetorial em uma tabela com menos de 100 linhas, a operação falha e retorna 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.

Prática recomendada: preencha a tabela com pelo menos 100 linhas antes de criar o índice de vetor. Para cenários de desenvolvimento e testes onde você precisa de menos linhas, funciona VECTOR_SEARCH sem índice usando uma abordagem de varredura bruta. No entanto, esse método degrada o desempenho com conjuntos de dados maiores.

Suporte a DML

Quando você cria um índice vetorial DiskANN usando a versão mais recente, a tabela não é mais somente leitura. Você pode modificar dados usando operações padrão de manipulação de dados (DML), e as mudanças aparecem automaticamente nos resultados de busca vetorial.

Essa funcionalidade torna a pesquisa de vetor adequada para cargas de trabalho transacionais dinâmicas em que os dados são alterados ao longo do tempo.

Notas de comportamento

• As operações DML não exigem a remoção ou a recriação do índice de vetor.
• As alterações são visíveis para consultas de pesquisa de vetor após a confirmação da transação.
• Para substituição de dados em larga escala (por exemplo, excluir a maioria das linhas e inserir um conjunto totalmente novo de inserções), considere remover e recriar o índice de vetor após a carga de dados para garantir a qualidade de pesquisa ideal.

Monitorando a manutenção do índice vetor

Os índices vetoriais executam a manutenção em segundo plano para incorporar alterações DML. Use a exibição de gerenciamento dinâmico sys.dm_db_vector_indexes para monitorar o status da tarefa de manutenção e integridade do índice.

Combinando índices de vetor com índices tradicionais

Os índices de vetor funcionam junto com os índices de árvore B tradicionais para fornecer o desempenho ideal da consulta. Ao usar a filtragem iterativa com VECTOR_SEARCH, considere a criação de índices tradicionais em colunas usadas em predicados de filtro.

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

Cenário de exemplo:

-- 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 consulta do SQL Server usa 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 de vetor identifica inserções semelhantes com base no vetor de consulta
• O índice tradicional em (category) filtra candidatos com eficiência durante o processo de pesquisa iterativa

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

Diretrizes de qualidade e manutenção de dados para índices vetoriais

Evitar conjuntos de dados com inserções duplicadas altas

A indexação de vetor funciona melhor quando as inserções representam conteúdo semântico diversificado. Não use conjuntos de dados com alta proporção de vetores duplicados para indexação vetorial.

A duplicação alta pode levar a:

• Qualidade de resultado ruim: vetores duplicados aparecem repetidamente em resultados, lotando correspondências semânticas mais relevantes.
• Eficácia reduzida: inserções duplicadas deslocam vizinhos melhores, reduzindo a utilidade da pesquisa de similaridade.
• Uso desnecessário de recursos: os índices de vetor são caros para compilar e manter, e duplicatas adicionam custo sem adicionar valor.

Prática recomendada: deduplicar inserções antes de criar um índice de vetor para melhorar o desempenho e a qualidade do resultado.

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

Índices vetoriais dão suporte a inserções, atualizações e exclusões. No entanto, quando você substitui a maioria ou todos os embeddings — por exemplo, reincorporando um conjunto de dados com um novo modelo — o índice existente pode não refletir mais a nova distribuição de dados.

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

• Consultas vetoriais continuam a devolver resultados válidos.
• A qualidade de recall e ranking pode se degradar, porque a estrutura do índice foi construída para uma distribuição de embedding diferente.

Prática recomendada: ao executar a substituição de dados quase completa (excluir e inserir novas inserções), remova e recrie o índice de vetor depois de carregar os novos dados. Recriar o índice garante que ele seja otimizado para a nova distribuição de inserção e restaure o comportamento previsível da consulta.

Problemas conhecidos

Para obter mais informações, examine os problemas conhecidos.

Permissões

Você precisa ALTER de permissão na mesa.

Exemplos

Baixe e importe o artigo da Wikipédia com exemplo de inserções de vetor .

Esses exemplos assumem uma tabela nomeada wikipedia_articles com uma coluna title_vector de tipo vector que armazena os embeddings de títulos dos artigos da Wikipédia. Ele title_vector utiliza um modelo de incorporação como text-embedding-ada-002 ou text-embedding-3-small, que retorna vetores com 1.536 dimensões.

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

Exemplo 1

O exemplo a seguir cria um índice de vetor na title_vector 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 a seguir cria um índice vetorial na title_vector coluna usando a métrica de produto (negativo dot ). Ele limita o paralelismo a 8 e armazena o vetor no SECONDARY grupo de arquivos.

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

Exemplo 3

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

O seguinte bloco de código demonstra com inserções CREATE VECTOR INDEX simuladas:

1. Ative o recurso de pré-visualização (necessário apenas para SQL Server 2025; não necessário para Banco de Dados SQL do Azure ou SQL Database no Fabric).
2. Crie uma tabela dbo.Articles de exemplo com uma coluna embedding com vetor de tipo de dados (5).
3. Insira 100 linhas de dados de exemplo com dados de inserção fictícios.
4. Criar um índice de vetor em dbo.Articles.embedding.
5. Demonstre a pesquisa de similaridade de vetor 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 consulta depende da versão do índice de vetor:

Para índices de versão anteriores (sintaxe preterida):

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: Trabalhando com operações DML

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

Excluir linhas

A exclusão de linhas as remove dos resultados da pesquisa de tabela e vetor.

DELETE FROM dbo.wikipedia_articles
WHERE id = 12345;

Após o término da operação de exclusão, a linha removida não aparece mais nas consultas de busca vetorial.

Inserir novas linhas

Você pode inserir novas linhas com inserções e elas se tornam imediatamente pesquisáveis sem recompilar 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 inserções recém-inseridas são incorporadas automaticamente ao índice de vetor e podem ser retornadas por consultas de pesquisa de vetor subsequentes.

Atualizar linhas existentes

Há suporte total para a atualização de colunas vetoriais ou não vetoriais.

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 você atualiza uma coluna vetorial, o índice é atualizado de acordo, então buscas vetoriais futuras usam a nova incorporação.

Uso MERGE para operações complexas

A MERGE instrução permite que você execute operações de inserção, atualização e exclusão em uma ú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 é atualizado automaticamente para refletir todas as alterações feitas pela MERGE instrução.

Conteúdo relacionado

• Pesquisa de vetor e índices de vetor no Mecanismo de Banco de Dados SQL
• Tipo de dados de vetor
• VECTOR_SEARCH (Transact-SQL)
• sys.vector_indexes (Transact-SQL)
• sys.dm_db_vector_indexes (Transact-SQL)
• Exemplos de Pesquisa de Vetores do Banco de Dados SQL do Azure