Compartilhar via

Tipo de dados vetoriais

Aplica-se a: SQL Server 2025 (17.x) Versão prévia do Banco de Dados SQL do Azurebanco de dadosSQL do Banco de Dados SQL do Azure banco de dados SQL gerenciadono Microsoft Fabric

O tipo de dados de vetor foi criado para armazenar dados de vetor otimizados para operações como a pesquisa de similaridade e aplicativos de aprendizado de máquina. Os vetores são armazenados em um formato binário otimizado, mas são expostos como matrizes JSON para conveniência. Cada elemento do vetor é armazenado como um valor de ponto flutuante com precisão única (4 bytes).

Para fornecer uma experiência familiar para desenvolvedores, o tipo de dados de vetor é criado e exibido como uma matriz JSON. Por exemplo, um vetor com três dimensões pode ser representado como '[0.1, 2, 30]'. A conversão implícita e explícita de e para o tipo de vetor pode ser feita usando os tipos varchar, nvarchar e json .

Observação

Para limitações, examine limitações e problemas conhecidos.

Os recursos de vetor estão disponíveis na Instância Gerenciada de SQL do Azure configurada com a política Always-up-to-date .

Para obter mais informações sobre como trabalhar com dados de vetor, consulte:

Sintaxe de exemplo

A sintaxe de uso para o tipo de vetor é semelhante a todos os outros tipos de dados do SQL Server em uma tabela.

column_name VECTOR( {<dimensions>} ) [NOT NULL | NULL]

Dimensões

Um vetor deve ter pelo menos uma dimensão. O número máximo de dimensões com suporte é 1998.

Exemplos

R. Definição de coluna

O tipo de vetor pode ser usado na definição de coluna contida em uma instrução CREATE TABLE, por exemplo:

O exemplo a seguir cria uma tabela com uma coluna de vetor e insere dados nela.

CREATE TABLE dbo.vectors
(
  id INT PRIMARY KEY,
  v VECTOR(3) NOT NULL
);

INSERT INTO dbo.vectors (id, v) VALUES 
(1, '[0.1, 2, 30]'),
(2, '[-100.2, 0.123, 9.876]'),
(3, JSON_ARRAY(1.0, 2.0, 3.0)); -- Using JSON_ARRAY to create a vector

SELECT * FROM dbo.vectors;

B. Uso em variáveis

O exemplo a seguir declara vetores usando o novo tipo de dados de vetor e calcula distâncias usando a função VECTOR_DISTANCE.

O tipo de vetor pode ser usado com variáveis:

DECLARE @v VECTOR(3) = '[0.1, 2, 30]';
SELECT @v;

C. Uso em funções ou procedimentos armazenados

O tipo de dados de vetor pode ser usado como parâmetro em funções ou procedimentos armazenados. Por exemplo:

CREATE PROCEDURE dbo.SampleStoredProcedure
@V VECTOR(3),
@V2 VECTOR(3) OUTPUT
AS
BEGIN
    SELECT @V;
    SET @V2 = @V;
END

Disponibilidade de recursos

O novo tipo de vetor está disponível em todos os níveis de compatibilidade do banco de dados.

Conversões

  • O tipo de vetor não pode ser usado com o tipo sql_variant ou atribuído a uma variável ou coluna de sql_variant. Essa restrição é semelhante a varchar(max), varbinary(max), nvarchar(max), xml, json e tipos de dados baseados em CLR.

Compatibilidade

Aprimoramentos no protocolo TDS

O SQL Server armazena vetores em um formato binário otimizado, mas os expõe como matrizes JSON para conveniência. Os drivers com suporte usam aprimoramentos no protocolo TDS para transmitir dados de vetor com mais eficiência no formato binário e apresentá-los a aplicativos como tipos de vetor nativos. Essa abordagem reduz o tamanho da carga, elimina a sobrecarga da análise JSON e preserva a precisão total do ponto flutuante. Como resultado, ele melhora o desempenho e a precisão ao trabalhar com vetores de alta dimensão em cenários de IA e machine learning.

Suporte a driver nativo

Os aplicativos que usam os drivers TDS versão 7.4 ou superior e atualizados podem ler, gravar, transmitir e copiar dados de vetor em massa nativamente.

Esses recursos exigem versões dos drivers listados abaixo. Verifique se você está usando a versão correta para habilitar o suporte a vetores nativos.

  • Microsoft.Data.SqlClient: a versão 6.1.0 apresenta o SqlVector tipo, estendendo System.Data.SqlDbTypes.
  • Microsoft JDBC Driver para SQL Server: a versão 13.1.0 Preview apresenta o microsoft.sql.Types.VECTOR tipo e a microsoft.sql.Vector classe.

Observação

Para clientes que não dão suporte ao protocolo TDS atualizado, o SQL Server continua a expor dados de vetor como tipos varchar(max) para garantir a compatibilidade com versões anteriores. Os aplicativos cliente podem trabalhar com dados de vetor como se fossem uma matriz JSON. O Mecanismo de Banco de Dados SQL converte automaticamente vetores de e para uma matriz JSON, tornando o novo tipo transparente para o cliente. Portanto, os drivers e todos os idiomas são automaticamente compatíveis com o novo tipo.

Você pode começar a usar o novo tipo de vetor imediatamente. Os exemplos a seguir mostram diferentes idiomas e configurações de driver.

Importante

Requer Microsoft.Data.SqlClient 6.1.0 ou posterior para suporte a vetor nativo.

static void InsertNonNullVal(SqlConnection conn)
{
    Console.WriteLine("Inserting non-null value with SqlDbType");

    using SqlCommand command = new SqlCommand("INSERT INTO dbo.vectors VALUES (@Id, @VectorData)", conn);

    command.Parameters.AddWithValue("@Id", 1);

    var vectorParameter = new SqlParameter("@VectorData", Microsoft.Data.SqlDbTypeExtensions.Vector);
    vectorParameter.Value = new Microsoft.Data.SqlTypes.SqlVectorFloat32(new float[] { 3.14159f, 1.61803f, 1.41421f });
    command.Parameters.Add(vectorParameter);

    command.ExecuteNonQuery();
}

static void ReadWithGetValue(SqlConnection connection)
{
    Console.WriteLine("Reading values using GetValue method:");

    using (SqlCommand commandSourceData = new SqlCommand("SELECT v FROM dbo.vectors;", connection))
    using (SqlDataReader reader = commandSourceData.ExecuteReader())
    while (reader.Read())
    {
        var vector = reader.GetValue(0);        
        if (vector != null && vector != DBNull.Value)
        {
            Console.WriteLine("Type: " + vector.GetType() + " Element Count: " + ((SqlVectorFloat32)vector).Length);

            var values = ((SqlVectorFloat32)vector).Values;
            Console.WriteLine("Values: " + string.Join(", ", values));
        }              
    }
}

Observação

Se você não estiver usando os drivers .NET mais recentes, ainda poderá trabalhar com dados de vetor em C# serializando e desserializando-os como uma cadeia de caracteres JSON usando a JsonSerializer classe. Isso garante a compatibilidade com a varchar(max) representação de vetores expostos pelo SQL Server para clientes mais antigos.

using Microsoft.Data.SqlClient;
using Dapper;
using DotNetEnv;
using System.Text.Json;

namespace DotNetSqlClient;

class Program
{
    static void Main(string[] args)
    {
        Env.Load();

        var v1 = new float[] { 1.0f, 2.0f, 3.0f };

        using var conn = new SqlConnection(Env.GetString("MSSQL"));
        conn.Execute("INSERT INTO dbo.vectors VALUES(100, @v)", param: new {@v = JsonSerializer.Serialize(v1)});

        var r = conn.ExecuteScalar<string>("SELECT v FROM dbo.vectors") ?? "[]";
        var v2 = JsonSerializer.Deserialize<float[]>(r); 
        Console.WriteLine(JsonSerializer.Serialize(v2));          
    }
}

Ferramentas

As seguintes ferramentas dão suporte ao tipo de dados de vetor :

Limitações

O tipo de vetor tem as seguintes limitações:

Tabelas

  • Não há suporte para restrições no nível de coluna, exceto para NULL/NOT NULL restrições.
    • DEFAULT e CHECK restrições não são suportadas para colunas de vetor.
    • Restrições de chave, como PRIMARY KEY ou FOREIGN KEY, não têm suporte para colunas de vetor . Igualdade, exclusividade, junções usando colunas de vetor como chaves e ordens de classificação não se aplicam a tipos de dados de vetor .
    • Não há noção de exclusividade para vetores, portanto, restrições exclusivas não são aplicáveis.
    • A verificação do intervalo de valores em um vetor também não é aplicável.
  • Os vetores não dão suporte a comparação, adição, subtração, multiplicação, divisão, concatenação ou qualquer outro operador matemático, lógico e de atribuição composta.
  • Colunas vetoriais não podem ser usadas em tabelas com otimização de memória.

Índices

  • Índices B-tree ou índices columnstore não são permitidos em colunas vetor. No entanto, uma coluna de vetor pode ser especificada como uma coluna incluída em uma definição de índice.

Metadados de esquema de tabela

  • O procedimento armazenado do sistema sp_describe_first_result_set não retorna corretamente o tipo de dados de vetor. Portanto, muitos clientes de acesso a dados e driver exibem um tipo de dados varchar ou nvarchar.

Tabelas do razão

  • O procedimento sp_verify_database_ledger armazenado gerará um erro se o banco de dados contiver uma tabela com uma coluna de vetor .

Tipos definidos pelo usuário

  • A criação do tipo de alias usando CREATE TYPE para o tipo de vetor não é permitida, semelhante ao comportamento dos tipos de dados xml e json.

Sempre Criptografado

  • Não há suporte para o tipo de vetor com o recurso Always Encrypted.

Problemas conhecidos

  • A máscara de dados atualmente mostra dados de vetor como tipo de dados varbinary no portal do Azure.

Conteúdo relacionado