Tipo de dados vetoriais

Aplica-se a: SQL Server 2025 (17.x) Banco de Dados SQL do AzureInstância Gerenciada de SQL do Azurebanco de dados SQL no Microsoft Fabric

O tipo de dado vetorial armazena dados vetoriais otimizados para operações como busca por similaridade e aplicações 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 de precisão simples (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]'. Você pode converter implícita e explicitamente entre o tipo vetor e os tipos varchar, nvarchar e json.

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

• Pesquisa de vetor e índices de vetor no Mecanismo de Banco de Dados SQL
• Aplicativos inteligentes

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 ]

Por padrão, o tipo base é float32. Para usar a meia precisão, especifique float16 explicitamente.

column_name VECTOR ( <dimensions> [ , <base_type> ] ) [ NOT NULL | NULL ]

Dimensions

Um vetor deve ter pelo menos uma dimensão. O número máximo de dimensões depende do tipo de base vetorial:

• Float32 suporta até 1.998 dimensões.
• O Float16 suporta até 3.996 dimensões.

Disponibilidade de funcionalidades

O tipo de dado vetorial está disponível em todos os níveis de compatibilidade com banco de dados. Se você não especificar um tipo base, o vetor usa float32.

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 .

Vetores float16 de meia precisão

• Vetores de meia-precisão (float16) estão geralmente disponíveis no Banco de Dados SQL do Azure, Instância Gerenciada de SQL do Azure e SQL Database no Microsoft Fabric. Nenhuma configuração de visualização é necessária.

• No SQL Server 2025 (17.x), vetores de meia-precisão (float16) estão disponíveis em pré-visualização. Para usar float16 no SQL Server 2025, você deve ativar a opção de configuração PREVIEW_FEATURES no escopo do banco de dados. Para mais informações, veja Habilitar recursos de pré-visualização no SQL Server 2025.

Para mais informações sobre vetores de meia precisão, veja Suporte a flutuadores de meia precisão no tipo de dado vetorial.

Habilitar recursos de pré-visualização no SQL Server 2025

Para alguns recursos de pré-visualização no SQL Server 2025, você deve ativar a PREVIEW_FEATURES opção de configuração com escopo de banco de dados.

ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;
GO

Para mais informações, veja PREVIEW_FEATURES.

Examples

A. Definição de coluna

Use o tipo de vetor em definições de colunas em uma instrução CREATE TABLE. Por exemplo:

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

Defina uma coluna vetorial em uma tabela usando o tipo base padrão float32 ou float16 para armazenamento de meia precisão.

CREATE TABLE dbo.vectors
(
    id INT PRIMARY KEY,
    v VECTOR(3) NOT NULL -- Uses default base type (**float32**)
);

CREATE TABLE dbo.vectors_fp16
(
    id INT PRIMARY KEY,
    v VECTOR(3, float16) -- Uses float16 for reduced storage and precision
);

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 dado vetorial e calcula distâncias usando a VECTOR_DISTANCE função.

Use o tipo vetorial com variáveis:

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

C. Uso em funções ou procedimentos armazenados

Você pode usar o tipo de dado vetorial como parâmetro em procedimentos ou funções armazenadas. Por exemplo:

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

Conversions

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

Compatibility

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 específicas dos drivers a seguir. 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.

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

using Microsoft.Data;
using Microsoft.Data.SqlClient;
using Microsoft.Data.SqlTypes;

namespace VectorSampleApp
{
    class Program
    {
        // Set your environment variable or fallback to local server
        private static readonly string connectionString =
            Environment.GetEnvironmentVariable("CONNECTION_STR")
            ?? "Server=tcp:localhost,1433;Database=Demo2;Integrated Security=True;TrustServerCertificate=True";

        private const int VectorDimensions = 3;
        private const string TableName = "dbo.Vectors";

        static void Main()
        {
            using var connection = new SqlConnection(connectionString);
            connection.Open();
            SetupTables(connection, TableName, VectorDimensions);
            InsertVectorData(connection, TableName);
            ReadVectorData(connection, TableName);
        }

        private static void SetupTables(SqlConnection connection, string tableName, int vectorDimensionCount)
        {
            using var command = connection.CreateCommand();

            command.CommandText = $@"
                IF OBJECT_ID('{tableName}', 'U') IS NOT NULL DROP TABLE {tableName};
                IF OBJECT_ID('{tableName}Copy', 'U') IS NOT NULL DROP TABLE {tableName}Copy;";
            command.ExecuteNonQuery();

            command.CommandText = $@"
                CREATE TABLE {tableName} (
                    Id INT IDENTITY(1,1) PRIMARY KEY,
                    VectorData VECTOR({vectorDimensionCount})
                );

                CREATE TABLE {tableName}Copy (
                    Id INT IDENTITY(1,1) PRIMARY KEY,
                    VectorData VECTOR({vectorDimensionCount})
                );";
            command.ExecuteNonQuery();
        }

        private static void InsertVectorData(SqlConnection connection, string tableName)
        {
            using var command = new SqlCommand($"INSERT INTO {tableName} (VectorData) VALUES (@VectorData)", connection);
            var param = command.Parameters.Add("@VectorData", SqlDbTypeExtensions.Vector);

            // Insert null using DBNull.Value
            param.Value = DBNull.Value;
            command.ExecuteNonQuery();

            // Insert non-null vector
            param.Value = new SqlVector<float>(new float[] { 3.14159f, 1.61803f, 1.41421f });
            command.ExecuteNonQuery();

            // Insert typed null vector
            param.Value = SqlVector<float>.CreateNull(VectorDimensions);
            command.ExecuteNonQuery();

            // Prepare once and reuse for loop
            command.Prepare();
            for (int i = 0; i < 10; i++)
            {
                param.Value = new SqlVector<float>(new float[]
                {
                    i + 0.1f,
                    i + 0.2f,
                    i + 0.3f
                });
                command.ExecuteNonQuery();
            }
        }

        private static void ReadVectorData(SqlConnection connection, string tableName)
        {
            using var command = new SqlCommand($"SELECT VectorData FROM {tableName}", connection);
            using var reader = command.ExecuteReader();

            while (reader.Read())
            {
                var sqlVector = reader.GetSqlVector<float>(0);

                Console.WriteLine($"Type: {sqlVector.GetType()}, IsNull: {sqlVector.IsNull}, Length: {sqlVector.Length}");

                if (!sqlVector.IsNull)
                {
                    float[] values = sqlVector.Memory.ToArray();
                    Console.WriteLine("VectorData: " + string.Join(", ", values));
                }
                else
                {
                    Console.WriteLine("VectorData: NULL");
                }
            }
        }
    }
}

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

@Test
public void getVectorData() throws SQLException {
    String query = "SELECT v FROM " + AbstractSQLGenerator.escapeIdentifier(tableName);
    try (PreparedStatement stmt = connection.prepareStatement(query)) {
        try (ResultSet rs = stmt.executeQuery()) {
            assertTrue(rs.next(), "No result found for inserted vector.");
            ResultSetMetaData meta = rs.getMetaData();
            int columnCount = meta.getColumnCount();

            while (rs.next()) {
                for (int i = 1; i <= columnCount; i++) {
                    String columnName = meta.getColumnName(i);
                    int columnType = meta.getColumnType(i); // from java.sql.Types

                    Object value = null;
                    switch (columnType) {
                        case Types.VARCHAR:
                        case Types.NVARCHAR:
                            value = rs.getString(i);
                            break;
                        case microsoft.sql.Types.VECTOR:
                            value = rs.getObject(i, microsoft.sql.Vector.class);
                    }

                    System.out.println(columnName + " = " + value + " (type: " + columnType + ")");
                }
                System.out.println("---");
            }
        }
    }
}

@Test
    public void getVectorData() throws SQLException {
        String query = "SELECT v FROM " + AbstractSQLGenerator.escapeIdentifier(tableName);
        try (PreparedStatement stmt = connection.prepareStatement(query)) {
            try (ResultSet rs = stmt.executeQuery()) {
                assertTrue(rs.next(), "No result found for inserted vector.");
                ResultSetMetaData meta = rs.getMetaData();
                int columnCount = meta.getColumnCount();

                while (rs.next()) {
                    for (int i = 1; i <= columnCount; i++) {
                        String columnName = meta.getColumnName(i);
                        int columnType = meta.getColumnType(i); // from java.sql.Types

                        Object value = null;
                        switch (columnType) {
                            case Types.VARCHAR:
                            case Types.NVARCHAR:
                                value = rs.getString(i);
                                break;
                            case microsoft.sql.Types.VECTOR:
                                value = rs.getObject(i, microsoft.sql.Vector.class);
                        }

                        System.out.println(columnName + " = " + value + " (type: " + columnType + ")");
                    }
                    System.out.println("---");
                }
            }
        }
    }

import json
import os, json
import mssql_python

connection_string = os.environ["MSSQL"]
conn = mssql_python.connect(connection_string)

cursor = conn.cursor()
query = "INSERT INTO dbo.vectors VALUES(100, ?)"
cursor.execute(query, json.dumps([1,2,3]))
cursor.close()

cursor = conn.cursor()
query = "SELECT v FROM dbo.vectors"
cursor.execute(query)
rows = cursor.fetchall()
for row in rows:
    print(json.loads(row[0]))
cursor.close()

conn.close()

Tools

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

• SQL Server Management Studio versão 21 e versões posteriores
• DacFX e SqlPackage versão 162.5 (novembro de 2024) e versões posteriores
• A extensão do SQL Server para Visual Studio Code versão 1.32 (maio de 2025) e versões posteriores
• Microsoft.Build.Sql versão 1.0.0 (março de 2025) e versões posteriores
• SQL Server Data Tools (Visual Studio 2022) versão 17.13 e versões posteriores

Limitations

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

Tables

• Restrições no nível da coluna não são compatíveis, exceto para restrições NULL e NOT NULL.

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

  • Verificar a faixa de valores dentro de um vetor 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.

• Você não pode usar colunas vetoriais em tabelas otimizadas para memória.

Indexes

• Você não pode usar índices de árvore B ou de armazenamento de colunas em colunas de vetor. No entanto, você pode incluir uma coluna vetorial como uma coluna incluída em uma definição de índice.
• Índices vetoriais criam um índice aproximado em uma coluna vetorial para melhorar o desempenho da busca por vizinhos mais próximos. Para saber mais sobre como funcionam a indexação vetorial e a busca vetorial, e as diferenças entre busca exata e aproximada, veja Busca vetorial e indexes vetoriais no SQL Mecanismo de Banco de Dados.

Metadados do esquema de tabela

• O procedimento armazenado do sistema sp_describe_first_result_set não retorna corretamente o tipo de dado vetorial . Como resultado, muitos clientes e drivers de acesso a dados identificam os tipos de dados varchar ou nvarchar.

Tabelas do razão

• O procedimento sp_verify_database_ledger armazenado gera um erro se o banco de dados contiver uma tabela com uma coluna vetorial .

Tipos definidos pelo usuário

• Você não pode criar um alias de tipo usando CREATE TYPE para o tipo vector. Essa restrição é semelhante ao comportamento dos tipos de dados xml e json .

Sempre Criptografado

• O tipo de vetor não é suportado pelo recurso Always Crypted.

Problemas conhecidos

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

Conteúdo relacionado

• Suporte a float de meia precisão no tipo de dados de vetor
• Pesquisa de vetor e índices de vetor no Mecanismo de Banco de Dados SQL
• Aplicativos inteligentes
• Funções vetor