CRIAR ÍNDICE VETORIAL (Transact-SQL) (Prévia)

Aplica-se a: SQL Server 2025 (17.x) Azure SQL Database SQLdatabase in Microsoft Fabric

Crie um índice aproximado em uma coluna de vetor para melhorar o desempenho da pesquisa de vizinhos mais próximos. Para saber mais sobre como funciona a indexação de vetores e a pesquisa de vetor e as diferenças entre a pesquisa exata e aproximada, consulte a pesquisa vetor e índices de vetor no Mecanismo de Banco de Dados SQL.

Banco de Dados SQL do Azure e banco de dados SQL no Fabric

O recurso está em prévia. Verifique limitações e considerações antes de prosseguir.

Disponibilidade regional

Esse recurso está sendo implantado no Banco de Dados SQL do Azure e no Banco de Dados SQL no Microsoft Fabric. Durante a distribuição, a disponibilidade e o comportamento podem variar por região e por versão de índice. Se um recurso ou sintaxe não estiver disponível, ele ficará disponível automaticamente à medida que a implantação for concluída. Para obter o status de disponibilidade regional atual, consulte a disponibilidade de recursos por região.

Recurso de Prévia do SQL Server 2025

No SQL Server 2025, essa função está em prévia e está sujeita a alterações. Para usar esse recurso, você deve habilitar a PREVIEW_FEATURES do banco de dados.

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

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.

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 executar operações INSERT, UPDATE, DELETE e MERGE, mantendo a funcionalidade de índice de vetor com manutenção automática de índice em tempo real
• Filtragem iterativa: predicados na cláusula WHERE são aplicados durante o processo de pesquisa de vetor, não após a recuperação
• Orientado pelo otimizador: o otimizador de consulta determina automaticamente se deve usar o índice DiskANN ou a pesquisa kNN com base nas características da consulta
• Quantização avançada: as técnicas de quantização de vetor foram integradas para fornecer melhor eficiência de armazenamento e desempenho de consulta mais rápido, com essas otimizações sendo transparentes para os usuários

Para obter detalhes sobre as limitações de versão do índice vetor anteriores, consulte a seção Limitações e considerações.

Migrando de versões de índice de vetor anteriores

Os índices de vetor criados usando uma versão anterior devem ser descartados e recriados para habilitar os recursos mais recentes. 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á dá suporte à filtragem iterativa, suporte a DML completo, execução controlada por otimizador e quantização aprimorada
• Nenhuma migração necessária

Criado usando uma versão anterior

• Usa o comportamento de pós-filtro herdado
• Não dá suporte aos recursos de pesquisa de vetor mais recentes
• A migração é altamente recomendada para garantir a compatibilidade futura

Etapa 2: Remover e recriar o índice de vetor

Índices de vetor criados usando um formato anterior não podem ser atualizados em vigor. 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

Após a recriação, verifique se o índice 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 do índice de vetor têm as seguintes limitações adicionais. Para verificar sua versão de índice, consulte Verificar a versão do índice.

• Somente após a filtragem: os predicados são aplicados somente após a recuperação de vetor, não durante o processo de pesquisa. Isso pode resultar em menos linhas retornadas do que o esperado quando os filtros são aplicados.

• Tabelas somente leitura: tabelas com índices de vetor são somente leitura. Nenhuma operação DML (INSERT, UPDATE, DELETE, MERGE) é permitida após a criação do índice de vetor. 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 de TOP_N: você deve ajustar manualmente o TOP_N parâmetro VECTOR_SEARCH para compensar a pós-filtragem, muitas vezes exigindo 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:

• Índices de vetor não podem ser particionados. Não há suporte para partição.

• A tabela deve ter um índice clusterizado de chave primária.

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

• Tabelas com índices vetoriais não podem ser truncadas 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 obter mais informações, consulte as restrições TRUNCATE TABLE.

Requisitos mínimos de dados

Os índices vetoriais exigem um número mínimo de linhas com valores de vetor não NULL antes que o índice possa ser criado.

• Contagem mínima de linhas: pelo menos 100 linhas com valores de vetor não NULL devem existir na tabela.
• Comportamento de erro: a tentativa de criar um índice de vetor em uma tabela com menos de 100 linhas falha com 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 teste em que menos linhas são necessárias, VECTOR_SEARCH funciona sem um índice usando uma abordagem de verificação de força bruta, embora o desempenho degrade com conjuntos de dados maiores.

Suporte a DML

Depois que um índice de vetor DiskANN é criado usando a versão mais recente, a tabela não é mais somente leitura. Você pode modificar dados livremente usando operações DML (linguagem de manipulação de dados) padrão e as alterações são refletidas automaticamente nos resultados da pesquisa de vetor.

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. Conjuntos de dados com uma alta proporção de vetores duplicados não são recomendados para indexação de vetor.

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 a maioria ou todas as inserções são substituídas, por exemplo, reinserindo 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:

• As consultas de pesquisa de vetor continuam a retornar resultados válidos
• Mas a qualidade de Recall e Classificação pode diminuir, pois a estrutura de índice foi criada para uma distribuição de inserção 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

O usuário deve ter ALTER permissão na tabela.

Exemplos

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

Exemplos pressupõem a existência de uma tabela nomeada wikipedia_articles com uma coluna title_vector de tipo vector que armazena inserções de título de artigos da Wikipédia. title_vector supõe-se que seja uma inserção gerada com um modelo de inserção como text-embedding-ada-002 ou text-embedding-3-small, que retorna vetores com 1.536 dimensões.

Para obter mais exemplos, incluindo soluções de ponta a ponta, acesse o repositório GitHub de Exemplos de Pesquisa de Vetor do Banco de Dados SQL do Azure.

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 de vetor na title_vector coluna usando a métrica do produto (negativo), dot limitando o paralelismo a 8 e armazenando 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

Um exemplo básico de ponta a ponta usando CREATE VECTOR INDEX e a função relacionada VECTOR_SEARCH . As inserções são simuladas. Em um cenário do mundo real, as inserções são geradas usando um modelo de inserção e AI_GENERATE_EMBEDDINGS ou uma biblioteca externa, como o SDK do OpenAI.

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

1. Habilita o recurso de visualização (necessário apenas para o SQL Server 2025; não é necessário para o Banco de Dados SQL do Azure ou o Banco de Dados SQL 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 ' + 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;

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

Depois que a exclusão for concluída, a linha removida não aparecerá mais em consultas de pesquisa de vetor.

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 uma coluna de vetor for atualizada, o índice será atualizado de acordo para que pesquisas futuras de vetor usem a nova inserção.

Usar 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 de vetor é atualizado automaticamente para refletir todas as alterações feitas pela instrução MERGE .

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) (versão prévia)
• sys.vector_indexes (Transact-SQL)
• sys.dm_db_vector_indexes (Transact-SQL)
• Exemplos de Pesquisa de Vetores do Banco de Dados SQL do Azure