Tipo de dados vetoriais

Aplica-se a: SQL Server 2025 (17.x) Base de Dados SQL do Azure AzureSQL Managed InstanceSQL database in Microsoft Fabric

O tipo de dados vetorial armazena dados vetoriais otimizados para operações como pesquisa por similaridade e aplicações de aprendizagem automática. Os vetores são armazenados em um formato binário otimizado, mas são expostos como matrizes JSON por conveniência. Cada elemento do vetor é armazenado como um valor de ponto flutuante de precisão única (4 bytes).

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

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

• Pesquisa vetorial e índices vetoriais no Mecanismo de Banco de Dados SQL
• Aplicações inteligentes

Sintaxe de exemplo

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

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

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

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 base do vetor:

• O 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 bases de dados. Se não especificar um tipo base, o vetor usa float32.

Os recursos de vetor estão disponíveis na Instância Gerida do 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 Base de Dados SQL do Azure, Azure SQL Managed Instance e SQL database no Microsoft Fabric. Não é necessária qualquer configuração de pré-visualização.

• 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, deve ativar a PREVIEW_FEATURES opção de configuração ao nível da base de dados. Para mais informações, consulte Ativar funcionalidades de pré-visualização no SQL Server 2025.

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

Ativar funcionalidades de pré-visualização no SQL Server 2025

Para algumas funcionalidades de pré-visualização no SQL Server 2025, deve ativar a PREVIEW_FEATURES opção de configuração com âmbito de base de dados.

ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;
GO

Para mais informações, consulte PREVIEW_FEATURES.

Examples

A. Definição da coluna

Utilize o tipo vector nas definições de colunas numa 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 numa 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 seguinte declara vetores usando o novo tipo de dado vetorial e calcula distâncias usando a VECTOR_DISTANCE função.

Use o tipo de vetor 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 procedimentos armazenados ou funções

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

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

Compatibility

Melhorias ao protocolo TDS

O SQL Server armazena vetores em um formato binário otimizado, mas os expõe como matrizes JSON por conveniência.

Os drivers suportados usam aprimoramentos no protocolo TDS para transmitir dados vetoriais de forma mais eficiente em formato binário e apresentá-los aos aplicativos como tipos de vetores nativos. Essa abordagem reduz o tamanho da carga útil, elimina a sobrecarga da análise JSON e preserva a precisão total do ponto flutuante. Como resultado, melhora o desempenho e a precisão ao trabalhar com vetores de alta dimensão em cenários de IA e aprendizado de máquina.

Suporte de drivers nativos

Os aplicativos que usam TDS versão 7.4 ou superior e drivers atualizados podem ler, gravar, transmitir e copiar dados vetoriais nativamente.

Estas capacidades requerem versões dos seguintes drivers. Certifique-se de que está a utilizar a versão correta para ativar o suporte vetorial nativo.

• Microsoft.Data.SqlClient: Versão 6.1.0 introduz o SqlVector tipo, estendendo System.Data.SqlDbTypes.
• Microsoft JDBC Driver for SQL Server: 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 suportam o tipo de dados vetoriais :

• 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

• As restrições ao nível da coluna não são suportadas, exceto as restrições de NULL e.NOT NULL

  • DEFAULT e CHECK não suportam restrições para colunas vetoriais.

  • Restrições de chave, como PRIMARY KEY ou FOREIGN KEY, não são suportadas para colunas vetoriais . Igualdade, exclusividade, junções usando colunas vetoriais como chaves e ordens de classificação não se aplicam a tipos de dados vetoriais .

  • Não há noção de exclusividade para vetores, portanto, restrições únicas não são aplicáveis.

  • Verificar o intervalo de valores dentro de um vetor não é aplicável.

• Os vetores não suportam comparação, adição, subtração, multiplicação, divisão, concatenação ou quaisquer outros operadores de atribuição matemática, lógica e composta.

• Não podes usar colunas vetoriais em tabelas otimizadas para memória.

Indexes

• Não é possível usar índices B-tree ou columnstore em colunas do tipo vector. No entanto, pode incluir uma coluna vetorial como uma coluna incluída numa definição de índice.
• Índices vetoriais criam um índice aproximado numa coluna vetorial para melhorar o desempenho da pesquisa por vizinhos mais próximos. Para saber mais sobre como funcionam a indexação vetorial e a pesquisa vetorial, e as diferenças entre pesquisa exata e aproximada, consulte Pesquisa vetorial e índices vetoriais no SQL Database Engine.

Metadados do esquema de tabela

• O procedimento armazenado do sistema sp_describe_first_result_set não devolve corretamente o tipo de dado vetorial . Como resultado, muitos clientes e controladores de acesso a dados consideram varchar ou nvarchar como um tipo de dados.

Tabelas contábeis

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

Tipos definidos pelo usuário

• Não podes criar um tipo de alias usando CREATE TYPE para o tipo vetorial . Esta restrição é semelhante ao comportamento dos tipos de dados xml e json .

Sempre criptografado

• O tipo de vetor não é suportado com a funcionalidade Always Encryption.

Problemas conhecidos

• Atualmente, o mascaramento de dados mostra dados vetoriais como dados do tipo varbinary no portal do Azure.

Conteúdo relacionado

• Suporte de flutuação de meia-precisão em tipos de dados vetoriais
• Pesquisa vetorial e índices vetoriais no Mecanismo de Banco de Dados SQL
• Aplicações inteligentes
• Funções vetoriais