CREATE VECTOR INDEX (Transact-SQL)

2025-06-16

Versão prévia do SQL Server 2025 (17.x)

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 vetores e as diferenças entre a pesquisa exata e aproximada, consulte vetores no Mecanismo de Banco de Dados SQL.

Recurso da versão preliminar

Observação

Esse recurso está em versão prévia e está sujeito a alterações. Leia os termos de uso da versão prévia no SLA (Contratos de Nível de Serviço) para Serviços Online.

Esse recurso está em versão prévia. Para usar esse recurso, você deve habilitar os seguintes sinalizadores de rastreamento:

DBCC TRACEON(466, 474, 13981, -1)

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 ]
    [ [,] DROP_EXISTING = { ON | OFF } ]
) ]
[ 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 .

METRIC = { 'cosseno' | 'dot' | 'euclidean' }

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 = 'DiskANN'

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

MAXDOP = max_degree_of_parallelism

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 o 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.

Observação

As operações de índice paralelo não estão disponíveis em todas as edições do Microsoft SQL Server. Para obter uma lista de recursos compatíveis com as edições do SQL Server, consulte Edições e recursos com suporte do SQL Server 2022 ou Editions e recursos com suporte do SQL Server 2025 Preview.

DROP_EXISTING = { ON | OFF }

É uma opção para remover e recompilar o índice de vetor existente com especificações modificadas e manter o mesmo nome para o índice. O padrão é OFF.

ON

Especifica remover e recompilar o índice existente, que deve ter o mesmo nome que o parâmetro index_name.
OFF

Especifica não remover e recompilar o índice existente. O SQL Server exibirá um erro se o nome do índice especificado já existir.

Limitações

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

O índice de vetor não pode ser particionado. Não há suporte para partição.
A tabela deve ter uma única coluna, um inteiro, um índice clusterizado de chave primária.
Uma tabela com um índice de vetor se torna somente leitura. Nenhuma modificação de dados é permitida enquanto o índice de vetor está presente na tabela.
Os índices vetoriais não são replicados para assinantes.

Permissões

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

Exemplos

Os detalhes do banco de dados usado no exemplo podem ser encontrados aqui: Baixe e importe o artigo da Wikipédia com o Vector Embeddings.

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 = 'cosine', 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 bloco de código a seguir cria incorporações simuladas com as seguintes etapas:

Habilita o sinalizador de rastreamento, necessário na versão prévia atual.
Crie uma tabela dbo.Articles de exemplo com uma coluna embedding com vetor de tipo de dados (5).
Insira dados de exemplo com dados de inserção fictícios.
Criar um índice de vetor em dbo.Articles.embedding.
Demonstre a pesquisa de similaridade de vetor com a VECTOR_SEARCH() função.

-- Step 0: Enable Preview Feature
DBCC TRACEON(466, 474, 13981, -1);
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
);

-- Step 2: Insert sample data
INSERT INTO Articles (id, title, content, embedding)
VALUES
(1, 'Intro to AI', 'This article introduces AI concepts.', '[0.1, 0.2, 0.3, 0.4, 0.5]'),
(2, 'Deep Learning', 'Deep learning is a subset of ML.', '[0.2, 0.1, 0.4, 0.3, 0.6]'),
(3, 'Neural Networks', 'Neural networks are powerful models.', '[0.3, 0.3, 0.2, 0.5, 0.1]'),
(4, 'Machine Learning Basics', 'ML basics for beginners.', '[0.4, 0.5, 0.1, 0.2, 0.3]'),
(5, 'Advanced AI', 'Exploring advanced AI techniques.', '[0.5, 0.4, 0.6, 0.1, 0.2]');

-- Step 3: Create a vector index on the embedding column
CREATE VECTOR INDEX vec_idx ON Articles(embedding)
WITH (metric = 'cosine', type = 'diskann');

-- Step 4: Perform a vector similarity search
DECLARE @qv VECTOR(5) = '[0.3, 0.3, 0.3, 0.3, 0.3]';
SELECT
    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;

Compartilhar via