Partilhar via

VETOR_SEARCH (Transact-SQL) (Pré-visualização)

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

Procure vetores semelhantes a um determinado vetor de consulta usando um algoritmo de pesquisa vetorial de vizinhos mais próximos aproximados. Para saber mais sobre como a indexação vetorial e a pesquisa vetorial funcionam, e as diferenças entre a pesquisa exata e aproximada, consulte Pesquisa vetorial e índices vetoriais no Mecanismo de Banco de dados SQL.

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

A funcionalidade está em pré-visualização. Certifique-se de verificar as limitações atuais antes de usá-lo.

Observação

Como funcionalidade de pré-visualização, a tecnologia apresentada neste artigo está sujeita aos Termos de Utilização Suplementares para Pré-visualizações do Microsoft Azure.

Importante

Para um desempenho ótimo e para aceder às capacidades mais recentes de pesquisa vetorial, utilize índices vetoriais criados com a versão mais recente. Para mais informações sobre como atualizar índices existentes e comparar versões, consulte CRIAR ÍNDICE VETORIAL - Atualizar índices vetoriais para a versão mais recente.

Disponibilidade regional

Esta funcionalidade está a ser implementada em Azure SQL Database e SQL Database no Microsoft Fabric. Durante o lançamento, a disponibilidade e o comportamento podem variar consoante a região e a versão do índice. Se uma funcionalidade ou sintaxe não estiver disponível, torna-se automaticamente disponível à medida que a implementação termina. Para o estado atual da disponibilidade regional, consulte Disponibilidade de funcionalidades por região.

Advertência

Aviso de descontinuação: O TOP_N parâmetro em VECTOR_SEARCH está obsoleto e mantido apenas para compatibilidade retroativa com índices vetoriais de versões anteriores. As novas implementações devem usar SELECT TOP (N) WITH APPROXIMATE sintaxe em vez disso. Para mais informações, consulte Sintaxe.

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

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

Certifique-se de verificar as limitações atuais antes de usá-lo.

Observação

A versão mais recente dos Vector Indexes está atualmente disponível apenas no Azure SQL Database e na base de dados SQL no Microsoft Fabric.

Principais melhorias com os índices vetoriais mais recentes

Índices vetoriais criados com a versão mais recente introduzem melhorias significativas:

  • 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 operações de INSERIR, ATUALIZAR, ELIMINAR e MERGE, mantendo a funcionalidade de índice vetorial com manutenção automática e em tempo real do índice
  • Filtragem iterativa: Os predicados na cláusula WHERE são aplicados 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: Técnicas de quantização vetorial foram integradas para proporcionar melhor eficiência de armazenamento e desempenho de consulta mais rápido, sendo estas otimizações transparentes para os utilizadores

Syntax

Transact-SQL convenções de sintaxe

Com a versão mais recente dos Vector Indexes:

Importante

Ao consultar tabelas que utilizam a versão mais recente do índice vetorial, a pesquisa vetorial aproximada deve usar a sintaxe aproximada TOP (N). Este requisito de sintaxe indica que a consulta está a pedir explicitamente resultados aproximados do vizinho mais próximo.

SELECT TOP (N) WITH APPROXIMATE
    column_list
FROM VECTOR_SEARCH(
        TABLE = object [ AS source_table_alias ]
        , COLUMN = vector_column
        , SIMILAR_TO = query_vector
        , METRIC = { 'cosine' | 'dot' | 'euclidean' }
    ) [ AS result_table_alias ]
[ WHERE predicate ]
ORDER BY distance;

Com versões anteriores, Índices Vetoriais:

VECTOR_SEARCH(
    TABLE = object [ AS source_table_alias ]
    , COLUMN = vector_column
    , SIMILAR_TO = query_vector
    , METRIC = { 'cosine' | 'dot' | 'euclidean' }
    , TOP_N = k
) [ AS result_table_alias ]

Importante

O TOP_N parâmetro não é suportado com índices vetoriais de última versão. Use a SELECT TOP (N) WITH APPROXIMATE sintaxe mostrada acima. Para mais informações, veja Erro usando sintaxe legacy.

Arguments

TABELA = objeto [AS source_table_alias]

Tabela em que se realiza a pesquisa. Deve ser uma tabela de base. Não há suporte para visualizações, tabelas temporárias, locais e globais.

COLUNA = vetor_column

A coluna vetorial na qual a pesquisa é realizada. A coluna deve ser um tipo de dados vetoriais .

SIMILAR_TO = query_vetor

O vetor usado para pesquisa. Deve ser uma variável ou uma coluna do tipo vetorial .

MÉTRICA = { 'cosseno' | 'ponto' | 'euclidiano' }

A métrica de distância usada para calcular a distância entre o vetor de consulta e os vetores na coluna especificada. Um índice ANN (Approximate Nearest Neighbor) é usado somente se um índice ANN correspondente, com a mesma métrica e na mesma coluna, for encontrado. Se não existirem índices ANN compatíveis, é emitido um aviso e utiliza-se o algoritmo kNN (k-vizinho mais próximo).

TOP_N = <k>

Advertência

Este parâmetro está obsoleto e mantido apenas para compatibilidade retrocedente com índices vetoriais de versões anteriores. Para índices de versões mais recentes, use SELECT TOP (N) WITH APPROXIMATE sintaxe em vez disso. As novas implementações devem usar a sintaxe mais recente.

O número máximo de vetores semelhantes que devem ser retornados. Deve ser um número inteiro positivo. Este parâmetro não é suportado com índices vetoriais criados com a versão mais recente.

result_table_alias

O alias é usado para fazer referência ao conjunto de resultados.

Conjunto de resultados de retorno

O conjunto de resultados retornado pela VECTOR_SEARCH função inclui:

  • Todas as colunas da tabela especificada no TABLE argumento.

  • Uma coluna adicional chamada distance, que representa a distância entre o vetor na coluna especificada pelo COLUMN argumento e o vetor fornecido no SIMILAR_TO argumento.

A coluna de distância é gerada pela VECTOR_SEARCH própria função, enquanto todas as outras colunas vêm da tabela referenciada TABLE no argumento.

Se você usar um alias para a tabela no TABLE argumento, deverá usar esse mesmo alias para fazer referência a SELECT suas colunas na instrução. Não é possível usar o alias atribuído às VECTOR_SEARCH colunas de referência da tabela especificada em TABLE. Esse comportamento é mais fácil de entender se você pensar no conjunto de resultados criado pegando a saída e mesclando-a com os dados da VECTOR_SEARCH tabela.

Se a tabela especificada no TABLE argumento já contiver uma coluna chamada distance, o comportamento será semelhante a uma junção SQL entre duas tabelas que compartilham um nome de coluna. Nesses casos, você deve usar aliases de tabela para desambiguar as referências de coluna — caso contrário, um erro será gerado.

Importante

A distance coluna é a única chave de ordem válida para resultados aproximados de pesquisa vetorial.

Limitations

  • Apenas por ordem crescente: A distance coluna deve estar ordenada por ordem crescente (ASC). A ordem decrescente (DESC) não é suportada.

Comportamento específico da versão

O comportamento de VECTOR_SEARCH varia consoante a versão do índice vetorial.

Versões anteriores de índice vetorial

Observação

Estas limitações aplicam-se apenas a índices vetoriais criados com versões anteriores. Migre para a versão mais recente para permitir a filtragem iterativa. Ver Migração a partir de versões anteriores de índice vetorial.

Apenas após filtragem: A pesquisa vetorial ocorre antes de aplicar qualquer predicado. Predicados adicionais são aplicados somente depois que os vetores mais semelhantes são retornados. O exemplo a seguir retorna as 10 principais linhas com incorporações mais semelhantes ao vetor @qvde consulta e, em seguida, aplica o predicado especificado na WHERE cláusula. Se nenhuma das 10 linhas associadas aos vetores retornados pela pesquisa vetorial tiver a accepted coluna igual a 1, o resultado estará vazio.

SELECT TOP (10) s.id,
                s.title,
                r.distance
FROM VECTOR_SEARCH(
         TABLE = dbo.sessions AS s,
         COLUMN = embedding,
         SIMILAR_TO = @qv,
         METRIC = 'cosine',
         TOP_N = 10
     ) AS r
WHERE accepted = 1
ORDER BY r.distance;

Limitações gerais

VECTOR_SEARCH não pode ser usado no corpo de uma exibição.

Examples

Importante

Ao consultar tabelas que utilizam a versão mais recente do índice vetorial, a pesquisa vetorial aproximada deve usar a TOP (N) WITH APPROXIMATE sintaxe. Este requisito de sintaxe indica que a consulta está a pedir explicitamente resultados aproximados do vizinho mais próximo.

O exemplo seguinte encontra os 10 artigos mais semelhantes na Pink Floyd music stylewikipedia_articles_embeddings tabela.

DECLARE @qv VECTOR(1536) = AI_GENERATE_EMBEDDINGS(N'Pink Floyd music style' USE MODEL Ada2Embeddings);

SELECT TOP (10) WITH APPROXIMATE
    t.id,
    t.title,
    r.distance
FROM VECTOR_SEARCH(
        TABLE = dbo.wikipedia_articles_embeddings AS t,
        COLUMN = content_vector,
        SIMILAR_TO = @qv,
        METRIC = 'cosine'
    ) AS r
ORDER BY r.distance;

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

Versão do índice vetorial Exemplo de sintaxe
Versão mais recente Utilização SELECT TOP (N) WITH APPROXIMATE sem TOP_N parâmetro
Versões anteriores (obsoletas) Usar TOP_N parâmetro na VECTOR_SEARCH função

Sugestão

Para determinar a sua versão do índice vetorial, veja Migrar a partir de versões anteriores do índice vetorial.

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

DECLARE @qv VECTOR(1536) = AI_GENERATE_EMBEDDINGS(N'Pink Floyd music style' USE MODEL Ada2Embeddings);

SELECT TOP (10)
    t.id,
    t.title,
    r.distance
FROM VECTOR_SEARCH(
        TABLE = dbo.wikipedia_articles_embeddings AS t,
        COLUMN = content_vector,
        SIMILAR_TO = @qv,
        METRIC = 'cosine',
        TOP_N = 10  -- Deprecated: Use SELECT TOP (N) WITH APPROXIMATE instead
    ) AS r
ORDER BY r.distance;

Observação

Usando o TOP_N parâmetro com a versão mais recente dos índices vetoriais, devolve o erro Msg 42274. Para informações detalhadas, veja Erro usando sintaxe legada na secção Comportamentos Esperados.

B. Fluxo de trabalho completo com criação de índice

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

Observação

Os índices vetoriais de última versão requerem pelo menos 100 linhas de dados antes da criação do índice. Este exemplo insere 100 linhas para cumprir este requisito. Para mais informações, consulte Requisitos mínimos de dados.

O bloco de código a seguir demonstra a VECTOR_SEARCH função com incorporações simuladas:

  1. Ativa a funcionalidade de pré-visualização (necessária apenas para SQL Server 2025; não é necessária para Azure SQL Database 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:

Versão do índice vetorial Exemplo de sintaxe
Versão mais recente Utilização SELECT TOP (N) WITH APPROXIMATE sem TOP_N parâmetro
Versões anteriores (obsoletas) Usar TOP_N parâmetro na VECTOR_SEARCH função

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  -- Deprecated: Use SELECT TOP (N) WITH APPROXIMATE instead
    ) AS s
ORDER BY s.distance, t.title;

C. Pesquisa vetorial com filtragem iterativa

O exemplo seguinte demonstra filtragem iterativa com índices vetoriais da versão mais recente. A consulta encontra artigos semelhantes enquanto aplica predicados durante o processo de pesquisa.

Com os índices da versão mais recente, os predicados na cláusula WHERE são aplicados durante o processo de pesquisa vetorial (não depois). O motor continua a procurar até encontrar 5 linhas qualificadas que cumprem todos os critérios:

  • Semelhança vetorial com "algoritmos de aprendizagem automática"
  • Categoria equivale a 'Tecnologia'
  • Estado publicado é igual a 1

Isto garante que obtém exatamente 5 resultados (se existirem) sem precisar de ajustar manualmente os parâmetros de pesquisa. Para uma comparação detalhada entre versões anteriores e mais recentes, veja Comportamento de filtragem iterativa na secção Comportamentos Esperados.

DECLARE @qv VECTOR(1536) = AI_GENERATE_EMBEDDINGS(N'machine learning algorithms' USE MODEL Ada2Embeddings);

SELECT TOP (5) WITH APPROXIMATE
    t.id,
    t.title,
    t.category,
    r.distance
FROM VECTOR_SEARCH(
        TABLE = dbo.wikipedia_articles AS t,
        COLUMN = content_vector,
        SIMILAR_TO = @qv,
        METRIC = 'cosine'
    ) AS r
WHERE t.category = 'Technology'
  AND t.published = 1
ORDER BY r.distance;

Observação

Certas operações SQL como GROUP BY, funções agregadas e funções janela requerem um padrão de subconsulta. Para detalhes, veja Combinar pesquisa vetorial com outras operações SQL.

D. Junções multi-tabela com INNER JOIN

O exemplo seguinte demonstra o INNER JOIN com filtragem em múltiplas tabelas. Use quando os embeddings são armazenados numa tabela separada dos dados principais da entity.

-- Assuming a schema with separate tables for articles and embeddings
DECLARE @qv VECTOR(1536) = AI_GENERATE_EMBEDDINGS(N'artificial intelligence and machine learning' USE MODEL Ada2Embeddings);

SELECT TOP (10) WITH APPROXIMATE
    a.id,
    a.title,
    a.category,
    vs.distance
FROM wikipedia_articles a
INNER JOIN VECTOR_SEARCH(
    TABLE = wikipedia_articles_embeddings AS e,
    COLUMN = content_vector,
    SIMILAR_TO = @qv,
    METRIC = 'cosine'
) AS vs ON a.id = e.article_id
WHERE e.approved = 1                           -- Iterative filter on embedding table
  AND a.category IN ('Technology', 'Science')  -- Filter on main table
  AND a.views > 50000
ORDER BY vs.distance;

Características principais deste exemplo:

  • Âmbito do alias da tabela: O alias e from TABLE = wikipedia_articles_embeddings AS e está disponível na cláusula WHERE para filtragem iterativa com índices de última versão

Comportamentos esperados

Erro usando sintaxe legada

Se tentar usar o TOP_N parâmetro em VECTOR_SEARCH ao consultar uma tabela 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:

  1. Remover o TOP_N parâmetro da VECTOR_SEARCH função
  2. Use SELECT TOP (N) WITH APPROXIMATE a sintaxe em vez disso

Incorreto (produz erro com o índice da versão mais recente):

SELECT TOP (10) 
    t.id,
    r.distance
FROM VECTOR_SEARCH(
        TABLE = dbo.wikipedia_articles AS t,
        COLUMN = title_vector,
        SIMILAR_TO = @qv,
        METRIC = 'cosine',
        TOP_N = 10  -- This parameter causes the error with latest version indexes
    ) AS r;

Correto (funciona com o índice da versão mais recente):

SELECT TOP (10) WITH APPROXIMATE  -- Specify TOP and WITH APPROXIMATE here
    t.id,
    r.distance
FROM VECTOR_SEARCH(
        TABLE = dbo.wikipedia_articles AS t,
        COLUMN = title_vector,
        SIMILAR_TO = @qv,
        METRIC = 'cosine'
        -- No TOP_N parameter
    ) AS r
ORDER BY r.distance;

Comportamento de filtragem iterativa

A versão mais recente introduz melhorias significativas em relação às versões anteriores de índice vetorial:

Aspeto Versão anterior Versão mais recente
Aplicação de predicados Os predicados relacionais foram aplicados após a pesquisa vetorial ter retornado um número fixo de vizinhos mais próximos (apenas após filtragem) Os predicados relacionais são aplicados durante o processo de pesquisa vetorial (filtragem iterativa)
Completude do resultado As consultas podiam devolver menos linhas—ou nenhumas—se os vizinhos mais próximos iniciais não cumprissem os filtros, mesmo quando existissem linhas qualificadas As consultas retornam o número esperado de linhas quando existem dados qualificados, sem ajustes manuais ou reescritas de consultas
Afinação TOP (N) Os utilizadores muitas vezes tinham de adivinhar ou sobreamostrar os valores TOP (N) para compensar o pós-filtragem Não é preciso adivinhar os valores TOP (N). O motor procura até encontrar linhas qualificatórias suficientes ou até que o espaço de pesquisa se esgote
Otimização de consultas Não aplicável O SQL Server seleciona automaticamente a estratégia de execução mais eficiente, incluindo alternar entre buscas vetoriais de índice e varrimentos kNN quando apropriado

Para um exemplo prático de filtragem iterativa, veja Exemplo C: Pesquisa vetorial com filtragem iterativa.

Requisitos da cláusula ORDER BY

Ao usar SELECT TOP (N) WITH APPROXIMATE, a cláusula ORDER BY tem requisitos específicos:

  • ORDER BY deve estar presente: Consultas sem a cláusula ORDER BY falham com erro .
  • Apenas a coluna de distância permitida: A cláusula ORDER BY deve referenciar apenas a coluna de distância do conjunto de resultados VECTOR_SEARCH. Incluir colunas adicionais falha com erro. Para ordenar por múltiplas colunas, use o padrão de subconsulta descrito em Múltiplas colunas ORDER BY.
  • Apenas por ordem crescente: A coluna de distância deve estar ordenada por ordem crescente (ASC). A ordem decrescente (DESC) não é suportada.

ORDEM VÁLIDA POR:

SELECT TOP (10) WITH APPROXIMATE
    t.id,
    t.title,
    r.distance
FROM VECTOR_SEARCH(
    TABLE = products,
    COLUMN = embedding,
    SIMILAR_TO = @query_vector,
    METRIC = 'cosine'
) AS r
INNER JOIN products t ON t.id = r.id
ORDER BY r.distance;  -- ✓ Valid

Padrões ORDER BY inválidos:

-- Missing ORDER BY
SELECT TOP (10) WITH APPROXIMATE
    r.distance
FROM VECTOR_SEARCH(
    TABLE = products,
    COLUMN = embedding,
    SIMILAR_TO = @query_vector,
    METRIC = 'cosine'
) AS r;
-- ✗ Error Msg 42248: APPROXIMATE cannot be used in a query without ORDER BY

-- Multiple columns in ORDER BY
SELECT TOP (10) WITH APPROXIMATE
    t.title,
    r.distance
FROM VECTOR_SEARCH(
    TABLE = products,
    COLUMN = embedding,
    SIMILAR_TO = @query_vector,
    METRIC = 'cosine'
) AS r
INNER JOIN products t ON t.id = r.id
ORDER BY r.distance, t.title;
-- ✗ Error Msg 42271: TOP WITH APPROXIMATE and VECTOR_SEARCH requires ORDER BY 
-- on distance column ascending, and no other columns

-- Descending order
SELECT TOP (10) WITH APPROXIMATE
    r.distance
FROM VECTOR_SEARCH(
    TABLE = products,
    COLUMN = embedding,
    SIMILAR_TO = @query_vector,
    METRIC = 'cosine'
) AS r
ORDER BY r.distance DESC;
-- ✗ Error Msg 42271: TOP WITH APPROXIMATE and VECTOR_SEARCH requires ORDER BY 
-- on distance column ascending, and no other columns

Comportamento sem índice vetorial

VECTOR_SEARCH pode executar consultas mesmo quando não existe um índice vetorial na coluna de destino. Sem um índice, a consulta realiza uma varredura completa da tabela (pesquisa k-vizinho mais próximo (kNN)) para calcular distâncias para todas as linhas.

Comportamento de consulta sem TOPO COM APROXIMAÇÃO

Ao usar VECTOR_SEARCH sem SELECT TOP (N) WITH APPROXIMATE, o comportamento da consulta depende da presença de TOP cláusulas e ORDER BY :

  • Sem TOP, sem ORDER BY, ou ORDER BY não-distância: varredura completa da tabela (pesquisa por força bruta) que calcula e devolve distâncias para todas as linhas
  • TOP (sem APROXIMAÇÃO) com ORDEM POR distância: Executa como uma pesquisa kNN (k-vizinhos mais próximos), que é uma pesquisa exata de vizinho mais próximo

Exemplo - Varredura completa com coluna de distância:

-- Returns all rows with calculated distances
SELECT 
    t.id,
    t.title,
    r.distance
FROM VECTOR_SEARCH(
    TABLE = dbo.wikipedia_articles AS t,
    COLUMN = title_vector,
    SIMILAR_TO = @qv,
    METRIC = 'cosine'
) AS r
ORDER BY t.id;  -- Not ordering by distance

Exemplo - pesquisa kNN (vizinhos mais próximos exatos):

-- Returns exact top 10 nearest neighbors using kNN
SELECT TOP (10)
    t.id,
    t.title,
    r.distance
FROM VECTOR_SEARCH(
    TABLE = dbo.wikipedia_articles AS t,
    COLUMN = title_vector,
    SIMILAR_TO = @qv,
    METRIC = 'cosine'
) AS r
ORDER BY r.distance;  -- No WITH APPROXIMATE = exact kNN

Usar SELECT TOP (N) WITH APPROXIMATE sem função VECTOR_SEARCH na consulta resulta num erro. A WITH APPROXIMATE cláusula requer que uma VECTOR_SEARCH função esteja presente.

Incorreto - Esta consulta falha:

-- Error: WITH APPROXIMATE requires VECTOR_SEARCH
SELECT TOP (10) WITH APPROXIMATE
    id,
    title,
    VECTOR_DISTANCE('cosine', title_vector, @qv) AS distance
FROM dbo.wikipedia_articles
WHERE title_vector IS NOT NULL
ORDER BY VECTOR_DISTANCE('cosine', title_vector, @qv);

Correto - Use VECTOR_SEARCH:

-- Correct: WITH APPROXIMATE with VECTOR_SEARCH
SELECT TOP (10) WITH APPROXIMATE
    t.id,
    t.title,
    r.distance
FROM VECTOR_SEARCH(
    TABLE = dbo.wikipedia_articles AS t,
    COLUMN = title_vector,
    SIMILAR_TO = @qv,
    METRIC = 'cosine'
) AS r
ORDER BY r.distance;

RESTRIÇÕES DA TABELA TRUNCADA

Tabelas com índices vetoriais não podem ser truncadas usando TRUNCATE TABLE. Para remover todos os dados de uma tabela indexada vetorialmente:

  1. Eliminar o índice vetorial
  2. Trunque a tabela
  3. Repovoar a tabela com pelo menos 100 linhas
  4. Recriar o índice vetorial

Exemplo de fluxo de trabalho:

-- Step 1: Drop the vector index
DROP INDEX idx_vector ON wikipedia_articles;

-- Step 2: Truncate the table
TRUNCATE TABLE wikipedia_articles;

-- Step 3: Repopulate with data (at least 100 rows)
-- ... insert operations ...

-- Step 4: Recreate the vector index
CREATE VECTOR INDEX idx_vector 
ON wikipedia_articles(title_vector)
WITH (METRIC = 'cosine');

Pode usar dicas de tabela com a VECTOR_SEARCH função para controlar o comportamento de execução de consultas. A FORCE_ANN_ONLY dica da tabela obriga o otimizador de consultas a usar apenas o índice aproximado do vizinho mais próximo (ANN), mesmo quando o otimizador poderia escolher uma estratégia de execução diferente.

Sintaxe:

FROM VECTOR_SEARCH(
    TABLE      = table_name,
    COLUMN     = column_name,
    SIMILAR_TO = vector_value,
    METRIC     = 'metric_name'
) AS alias WITH (FORCE_ANN_ONLY)

Exemplo:

O exemplo seguinte força a utilização do índice aproximado do vizinho mais próximo para a consulta de pesquisa vetorial:

DECLARE @qembedding VECTOR(1536) = AI_GENERATE_EMBEDDINGS(N'artificial intelligence' USE MODEL Ada2Embeddings);

SELECT TOP 50 WITH APPROXIMATE
    t.id,
    t.title,
    r.distance
FROM VECTOR_SEARCH(
    TABLE      = dbo.wikipedia_articles AS t,
    COLUMN     = title_vector,
    SIMILAR_TO = @qembedding,
    METRIC     = 'cosine'
) AS r WITH (FORCE_ANN_ONLY)
ORDER BY r.distance;

Use FORCE_ANN_ONLY quando quiser garantir que a consulta utiliza a estratégia aproximada de índice de vizinho mais próximo, sobrepondo-se à seleção automática da estratégia do otimizador.

Observação

Usar FORCE_ANN_ONLY requer ambos:

  • Um índice vetorial na coluna alvo
  • SELECT TOP (N) WITH APPROXIMATE na consulta

Se algum dos requisitos estiver em falta, a consulta falha porque não pode usar a estratégia aproximada do vizinho mais próximo que a dica força.

Combinação de pesquisa vetorial com outras operações SQL

A VECTOR_SEARCH função tem TOP (N) WITH APPROXIMATE requisitos específicos para a sua utilização. Algumas operações SQL podem ser usadas diretamente com pesquisa vetorial, enquanto outras requerem um padrão de subconsulta.

Operações que requerem o padrão de subquery

Quando precisares de realizar operações que não são diretamente compatíveis com TOP (N) WITH APPROXIMATE, usa pesquisa vetorial numa subconsulta (consulta interna), depois aplica as tuas operações na consulta externa. Este padrão mantém os benefícios de desempenho da pesquisa vetorial aproximada enquanto permite a funcionalidade completa do SQL.

Sugestão

O padrão de subquery funciona para qualquer operação que não possa ser combinada diretamente com TOP (N) WITH APPROXIMATE. Aplique pesquisa vetorial na consulta interna e depois use qualquer operação SQL na consulta externa.

Cenários comuns

A tabela seguinte lista as operações que requerem o padrão de subconsulta:

Funcionamento Exemplo de caso de uso
AGRUPAR POR Calcular estatísticas por categoria
Funções agregadas Contagem geral, média, mínimo, máximo nos resultados
Funções do Windows ROW_NUMBER, PATENTE, DENSE_RANK, NTILE
Definir operações UNIÃO, UNIÃO TODOS, EXCETO, CRUZAM-SE
Múltiplas colunas ORDER BY Ordena por distância, depois por data ou título
DISTINTO Remover resultados duplicados
APLICAÇÃO CRUZADA Aplicar pesquisa vetorial por linha da tabela exterior

GROUP BY e funções agregadas

O exemplo seguinte mostra a distância média dos artigos que mais correspondem por categoria. Neste exemplo, foi adicionada uma category coluna à wikipedia_articles tabela para classificar artigos.

DECLARE @qv VECTOR(1536) = AI_GENERATE_EMBEDDINGS(N'machine learning' USE MODEL Ada2Embeddings);

SELECT 
    category,
    COUNT(*) AS article_count,
    AVG(distance) AS avg_distance,
    MIN(distance) AS closest_match
FROM (
    SELECT TOP (100) WITH APPROXIMATE
        t.id,
        t.title,
        t.category,
        r.distance
    FROM VECTOR_SEARCH(
        TABLE = dbo.wikipedia_articles AS t,
        COLUMN = title_vector,
        SIMILAR_TO = @qv,
        METRIC = 'cosine'
    ) AS r
    ORDER BY r.distance
) AS vector_results
GROUP BY category
ORDER BY avg_distance;

Funções do Windows

O exemplo seguinte classifica os artigos por similaridade e atribui quartis.

DECLARE @qv VECTOR(1536) = AI_GENERATE_EMBEDDINGS(N'neural networks' USE MODEL Ada2Embeddings);

SELECT 
    id,
    title,
    category,
    distance,
    ROW_NUMBER() OVER (ORDER BY distance) AS rank,
    NTILE(4) OVER (ORDER BY distance) AS quartile
FROM (
    SELECT TOP (100) WITH APPROXIMATE
        t.id,
        t.title,
        t.category,
        r.distance
    FROM VECTOR_SEARCH(
        TABLE = dbo.wikipedia_articles AS t,
        COLUMN = title_vector,
        SIMILAR_TO = @qv,
        METRIC = 'cosine'
    ) AS r
    ORDER BY r.distance
) AS vector_results
WHERE distance < 0.5
ORDER BY rank;

Operações de conjunto (UNIÃO, INTERSECÇÃO, EXCETO)

O exemplo seguinte combina resultados de duas consultas de pesquisa diferentes usando UNION.

DECLARE @qv1 VECTOR(1536) = AI_GENERATE_EMBEDDINGS(N'artificial intelligence' USE MODEL Ada2Embeddings);
DECLARE @qv2 VECTOR(1536) = AI_GENERATE_EMBEDDINGS(N'machine learning' USE MODEL Ada2Embeddings);

SELECT id, title, 'AI Search' AS source
FROM (
    SELECT TOP (50) WITH APPROXIMATE
        t.id,
        t.title,
        r.distance
    FROM VECTOR_SEARCH(
        TABLE = dbo.wikipedia_articles AS t,
        COLUMN = title_vector,
        SIMILAR_TO = @qv1,
        METRIC = 'cosine'
    ) AS r
    ORDER BY r.distance
) AS ai_results

UNION

SELECT id, title, 'ML Search' AS source
FROM (
    SELECT TOP (50) WITH APPROXIMATE
        t.id,
        t.title,
        r.distance
    FROM VECTOR_SEARCH(
        TABLE = dbo.wikipedia_articles AS t,
        COLUMN = title_vector,
        SIMILAR_TO = @qv2,
        METRIC = 'cosine'
    ) AS r
    ORDER BY r.distance
) AS ml_results
ORDER BY id;

DISTINTO

O exemplo seguinte obtém categorias distintas a partir dos artigos com melhor correspondência.

DECLARE @qv VECTOR(1536) = AI_GENERATE_EMBEDDINGS(N'deep learning' USE MODEL Ada2Embeddings);

SELECT DISTINCT category
FROM (
    SELECT TOP (100) WITH APPROXIMATE
        t.id,
        t.category,
        r.distance
    FROM VECTOR_SEARCH(
        TABLE = dbo.wikipedia_articles AS t,
        COLUMN = title_vector,
        SIMILAR_TO = @qv,
        METRIC = 'cosine'
    ) AS r
    ORDER BY r.distance
) AS vector_results
WHERE distance < 0.7
ORDER BY category;

Múltiplas colunas ORDER BY

O exemplo seguinte ordena por distância e depois por título para empates.

DECLARE @qv VECTOR(1536) = AI_GENERATE_EMBEDDINGS(N'quantum computing' USE MODEL Ada2Embeddings);

SELECT 
    id,
    title,
    category,
    distance
FROM (
    SELECT TOP (100) WITH APPROXIMATE
        t.id,
        t.title,
        t.category,
        r.distance
    FROM VECTOR_SEARCH(
        TABLE = dbo.wikipedia_articles AS t,
        COLUMN = title_vector,
        SIMILAR_TO = @qv,
        METRIC = 'cosine'
    ) AS r
    ORDER BY r.distance
) AS vector_results
ORDER BY distance, title;

APLICAÇÃO CRUZADA

Ao usar SELECT TOP (N) WITH APPROXIMATE com VECTOR_SEARCH, não pode usar CROSS APPLY nem OUTER APPLY na mesma FROM cláusula. Isto aplica-se mesmo que não haja referência externa dentro da VECTOR_SEARCH função.

Uma consulta com CROSS APPLY realizaria logicamente múltiplas pesquisas vetoriais (uma por linha da tabela exterior) e fundiria todos os resultados num único fluxo ordenado. O algoritmo aproximado do vizinho mais próximo não consegue fundir eficientemente resultados de múltiplas pesquisas vetoriais independentes mantendo as garantias aproximadas e as características de desempenho.

Padrão que produz um erro:

-- This query is NOT supported
SELECT TOP (100) WITH APPROXIMATE
    o.id,
    vs.title,
    vs.distance
FROM Orders AS o
    CROSS APPLY VECTOR_SEARCH(
        TABLE = Products,
        COLUMN = embedding,
        SIMILAR_TO = o.customer_preference_vector,
        METRIC = 'cosine'
    ) AS vs
WHERE o.order_date > '2026-01-01'
ORDER BY vs.distance;

Este padrão tenta encontrar produtos semelhantes para a preferência de cada encomenda, mas não pode ser executado com um plano aproximado de pesquisa vetorial.

Padrão recomendado:

Para obter resultados semelhantes, use uma subquery com TOP (N) WITH APPROXIMATE no CROSS APPLY próprio site:

-- This query IS supported
SELECT
    o.id,
    vs.title,
    vs.distance
FROM Orders AS o
    CROSS APPLY (
        SELECT TOP (10) WITH APPROXIMATE
            p.title,
            r.distance
        FROM VECTOR_SEARCH(
            TABLE = Products AS p,
            COLUMN = embedding,
            SIMILAR_TO = o.customer_preference_vector,
            METRIC = 'cosine'
        ) AS r
        ORDER BY r.distance
    ) AS vs
WHERE o.order_date > '2026-01-01';

Neste padrão:

  • Cada pesquisa vetorial está limitada aos 10 principais resultados dentro da subconsulta
  • A consulta externa não usa WITH APPROXIMATE
  • Os resultados são devidamente definidos por linha a partir da tabela exterior

Operações que funcionam diretamente

As seguintes operações podem ser usadas diretamente com VECTOR_SEARCH sem necessidade de subconsulta:

Conteúdo relacionado

  • Last updated on