VECTOR_SEARCH (Transact-SQL) (versão prévia)

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

Pesquise vetores semelhantes a determinados vetores de consulta usando um algoritmo de pesquisa de vetor próximo aproximado. 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 as limitações atuais antes de usá-la.

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.

Principais aprimoramentos com os índices de vetor mais recentes

Os índices de vetor criados com a versão mais recente introduzem aprimoramentos significativos:

• 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

Syntax

Convenções de sintaxe de Transact-SQL

Com os Índices vetoriais da versão mais recente:

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 índices vetoriais de versão anterior:

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 ]

Arguments

TABLE = objeto [AS source_table_alias]

Tabela na qual executar a pesquisa. Deve ser uma tabela base. Não há suporte para exibições, tabelas temporárias, locais e globais.

COLUNA = vector_column

A coluna de vetor na qual a pesquisa é executada. A coluna deve ser um tipo de dados de vetor .

SIMILAR_TO = query_vector

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

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

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 (Vizinho Mais Próximo Aproximado) é usado somente se um índice ANN correspondente, com a mesma métrica e na mesma coluna, for encontrado. Se não houver índices ANN compatíveis, um aviso será gerado e o algoritmo kNN (vizinho k-mais próximo) será usado.

TOP_N = <k>

O número máximo de vetores semelhantes que devem ser retornados. Deve ser um inteiro positivo. Não há suporte para esse parâmetro com índices de vetor criados usando 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 especificadas 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 função em si, enquanto todas as outras colunas vêm da tabela referenciada no TABLE argumento.

Se você usar um alias para a tabela no TABLE argumento, deverá usar esse mesmo alias para referenciar suas colunas na SELECT instrução. Você não pode usar o alias atribuído a 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 usando a saída VECTOR_SEARCH e mesclando-a com os dados da tabela.

Se a tabela especificada no TABLE argumento já contiver uma coluna nomeada 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.

Limitations

• Somente ordem crescente: a distance coluna deve ser ordenada em ordem crescente (ASC). Não há suporte para DESC (ordem decrescente).

Comportamento específico da versão

O comportamento varia VECTOR_SEARCH dependendo da versão do índice de vetor.

Versões anteriores do índice de vetor

Somente pós-filtragem: a pesquisa de vetor 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 inserções mais semelhantes ao vetor @qvde consulta e aplica o predicado especificado na WHERE cláusula. Se nenhuma das 10 linhas associadas aos vetores retornados pela pesquisa de vetor 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

A. Pesquisa básica de similaridade de vetor

O exemplo a seguir localiza os 10 artigos mais semelhantes à 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 consulta depende da versão do índice de vetor:

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

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;

B. Concluir o fluxo de trabalho com a criação do índice

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 demonstra a VECTOR_SEARCH função com inserções 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 ' || [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  -- Deprecated: Use SELECT TOP (N) WITH APPROXIMATE instead
    ) AS s
ORDER BY s.distance, t.title;

C. Pesquisa de vetor com filtragem iterativa

O exemplo a seguir demonstra a filtragem iterativa com índices de vetor de versão mais recentes. A consulta localiza artigos semelhantes ao aplicar predicados durante o processo de pesquisa.

Com os índices de versão mais recentes, os predicados na cláusula WHERE são aplicados durante o processo de pesquisa de vetor (não depois). O mecanismo continua pesquisando até encontrar cinco linhas de qualificação que correspondam a todos os critérios:

• Similaridade de vetor com "algoritmos de aprendizado de máquina"
• Categoria igual a 'Tecnologia'
• O status publicado é igual a 1

Isso garante que você obtenha exatamente 5 resultados (se eles existirem) sem ajustar manualmente os parâmetros de pesquisa. Para obter uma comparação detalhada entre versões anteriores e mais recentes, consulte o comportamento de filtragem iterativa na seçã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;

D. Junções de várias tabelas com INNER JOIN

O exemplo a seguir demonstra o INNER JOIN com filtragem em várias tabelas. Use quando as inserções são armazenadas em uma tabela separada dos dados da entidade principal.

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

Principais recursos deste exemplo:

• Escopo do alias da tabela: o alias e está disponível na cláusula WHERE para filtragem iterativa com índices de TABLE = wikipedia_articles_embeddings AS e versão mais recentes

Comportamentos esperados

Erro ao usar a sintaxe herdada

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

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

Incorreto (produz erro com o índice de 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 de 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 apresenta melhorias significativas em relação às versões anteriores do índice vetor:

Para obter um exemplo prático de filtragem iterativa, consulte Exemplo C: Pesquisa de vetor 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: as consultas sem uma cláusula ORDER BY falham com o erro.
• Somente 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. A inclusão de colunas adicionais falha com o erro. Para classificar por várias colunas, use o padrão de subconsulta descrito em várias colunas ORDER BY.
• Somente ordem crescente: a coluna de distância deve ser ordenada em ordem crescente (ASC). Não há suporte para DESC (ordem decrescente).

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 um índice de vetor

VECTOR_SEARCH pode executar consultas mesmo quando nenhum índice de vetor existe na coluna de destino. Sem um índice, a consulta executa uma verificação de tabela completa (pesquisa k-nearest neighbor (kNN) para calcular distâncias para todas as linhas.

Comportamento de consulta sem TOP WITH APPROXIMATE

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

• Sem TOP, sem ORDER BY ou ORDER BY sem distância: verificação de tabela completa (pesquisa de força bruta) que calcula e retorna distâncias para todas as linhas
• TOP (sem APROXIMAÇÃO) com a distância ORDER BY: executa como uma pesquisa kNN (k-nearest neighbors), que é exatamente uma pesquisa de vizinho mais próxima

Exemplo – Verificação completa com a 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 (exatamente vizinhos mais próximos):

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

TOP WITH APPROXIMATE sem VECTOR_SEARCH

Usar SELECT TOP (N) WITH APPROXIMATE sem uma VECTOR_SEARCH função na consulta resulta em um 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 – Usar 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 de TRUNCATE TABLE

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

1. Remover o índice de vetor
2. Truncar a tabela
3. Repovoar a tabela com pelo menos 100 linhas
4. Recriar o índice de vetor

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

Dicas de tabela para pesquisa de vetor

Você pode usar dicas de tabela com a função para controlar o VECTOR_SEARCH comportamento de execução da consulta. A FORCE_ANN_ONLY dica de tabela força o otimizador de consulta a usar apenas o índice ann (vizinho mais próximo) aproximado, mesmo quando o otimizador pode escolher outra estratégia de execução.

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 a seguir força o uso do índice vizinho mais próximo aproximado para a consulta de pesquisa de vetor:

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 use a estratégia de índice vizinho mais próxima aproximada, substituindo a seleção de estratégia automática do otimizador.

Combinando a pesquisa de vetor com outras operações sql

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

Operações que exigem padrão de subconsulta

Quando precisar executar operações que não são diretamente compatíveis, TOP (N) WITH APPROXIMATEuse a pesquisa de vetor em uma subconsulta (consulta interna) e aplique suas operações na consulta externa. Esse padrão mantém os benefícios de desempenho da pesquisa de vetor aproximada ao habilitar a funcionalidade completa do SQL.

Cenários comuns

A tabela a seguir lista as operações que exigem o padrão de subconsulta:

AGRUPAR POR e agregar funções

O exemplo a seguir localiza a distância média dos principais artigos correspondentes por categoria. Para este exemplo, uma category coluna foi adicionada à 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 da janela

O exemplo a seguir classifica os artigos por similaridade e atribui quartils.

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;

Definir operações (UNION, INTERSECT, EXCEPT)

O exemplo a seguir 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;

DISTINCT

O exemplo a seguir obtém categorias distintas dos principais artigos correspondentes.

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;

Várias colunas ORDER BY

O exemplo a seguir classifica por distância e, em seguida, 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;

CROSS APPLY

Ao usar SELECT TOP (N) WITH APPROXIMATE com VECTOR_SEARCH, você não pode usar CROSS APPLY ou OUTER APPLY na mesma FROM cláusula. Isso se aplica mesmo se não houver nenhuma referência externa dentro da VECTOR_SEARCH função.

Uma consulta com CROSS APPLY a qual executaria logicamente várias pesquisas de vetor (uma por linha da tabela externa) e mesclaria todos os resultados em um único fluxo ordenado. O algoritmo vizinho mais próximo aproximado não pode mesclar com eficiência os resultados de várias pesquisas de vetor 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;

Esse padrão tenta encontrar produtos semelhantes para a preferência do cliente de cada pedido, mas não pode ser executado com um plano de pesquisa de vetor aproximado.

Padrão recomendado:

Para obter resultados semelhantes, use uma subconsulta em TOP (N) WITH APPROXIMATECROSS APPLY si:

-- 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 de vetor é limitada aos 10 principais resultados na subconsulta
• A consulta externa não usa WITH APPROXIMATE
• Os resultados são definidos corretamente por linha da tabela externa

Operações que funcionam diretamente

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

• INNER JOIN – Veja o exemplo D: Junções de várias tabelas com INNER JOIN
• Predicados WHERE – Aplicar iterativa ou pós-filtragem
• Distância DE ORDEM ÚNICA POR

Conteúdo relacionado

• Pesquisa de vetor e índices de vetor no Mecanismo de Banco de Dados SQL
• Tipo de dados de vetor
• CRIAR ÍNDICE DE VETOR (Transact-SQL)
• sys.dm_db_vector_indexes (Transact-SQL)
• Exemplos de Pesquisa de Vetores do Banco de Dados SQL do Azure