Tipo di dati vettoriali

Si applica a: SQL Server 2025 (17.x) Database SQL di AzureIstanza gestita di SQL di AzureDatabase SQL in Microsoft Fabric

Il tipo di dato vettoriale memorizza dati vettoriali ottimizzati per operazioni come la ricerca di similarità e applicazioni di machine learning. I vettori vengono archiviati in un formato binario ottimizzato, ma vengono esposti come matrici JSON per praticità. Ogni elemento del vettore viene archiviato come valore a virgola mobile a precisione singola (4 byte).

Per offrire agli sviluppatori un'esperienza familiare, il tipo di dati vector viene creato e visualizzato come matrice JSON. Ad esempio, un vettore con tre dimensioni può essere rappresentato come '[0.1, 2, 30]'. Puoi convertire implicitamente ed esplicitamente tra il tipo vettoriale e i tipi varchar, nvarchar e json .

Per altre informazioni sull'uso dei dati vettoriali, vedere:

• Ricerca vettoriale e indici vettoriali nel motore di database SQL
• Applicazioni intelligenti

Sintassi di esempio

La sintassi di utilizzo per il tipo vector è simile a tutti gli altri tipi di dati di SQL Server in una tabella.

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

Di default, il tipo base è float32. Per usare la precisione dimezzata, specifica esplicitamente float16.

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

Dimensions

Un vettore deve avere almeno una dimensione. Il numero massimo di dimensioni dipende dal tipo di base vettoriale:

• Float32 supporta fino a 1.998 dimensioni.
• Float16 supporta fino a 3.996 dimensioni.

Disponibilità delle funzionalità

Il tipo di dato vettoriale è disponibile sotto tutti i livelli di compatibilità del database. Se non specifichi un tipo base, il vettore usa float32.

Le funzionalità vettoriali sono disponibili in Istanza gestita di SQL di Azure configurata con i criteri Always-up-to-date .

Vettori float16 a precisione dimezzata

• I vettori a mezza precisione (float16) sono generalmente disponibili in database SQL di Azure, Istanza gestita di SQL di Azure e database SQL in Microsoft Fabric. Non è richiesta alcuna configurazione di anteprima.

• In SQL Server 2025 (17.x), i vettori a mezza precisione (float16) sono disponibili in anteprima. Per utilizzare float16 in SQL Server 2025, devi abilitare l'opzione PREVIEW_FEATURES di configurazione con ambito del database. Per ulteriori informazioni, consulta Abilita le funzionalità di anteprima in SQL Server 2025.

Per ulteriori informazioni sui vettori a mezza precisione, vedi Supporto a galleggiante a metà precisione nel tipo di dato vettoriale.

Abilita le funzionalità di anteprima in SQL Server 2025

Per alcune funzionalità di anteprima in SQL Server 2025, devi abilitare l'opzione PREVIEW_FEATURES di configurazione con ambito del database.

ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;
GO

Per maggiori informazioni, vedi PREVIEW_FEATURES.

Examples

A. Definizione di colonna

Usa il tipo vettoriale nelle definizioni di colonne all'interno di un'istruzione CREATE TABLE . Per esempio:

Nell'esempio seguente viene creata una tabella con una colonna vettoriale e vengono inseriti dati.

Definisci una colonna vettoriale in una tabella usando il tipo base predefinito float32 o float16 per la memoria a mezza precisione.

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. Utilizzo nelle variabili

Il seguente esempio dichiara i vettori usando il nuovo tipo di dato vettoriale e calcola le distanze usando la VECTOR_DISTANCE funzione.

Usa il tipo vettoriale con variabili:

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. Utilizzo in procedure memorizzate o funzioni

Puoi usare il tipo di dato vettoriale come parametro nelle stored procedure o funzioni. Per esempio:

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

Conversions

• Non puoi usare il tipo vettoriale con il tipo sql_variant o assegnarlo a una variabile o colonna sql_variant . Questa restrizione è simile ai tipi di dati varchar(max), varbinary(max), nvarchar(max), xml, json e CLR.

Compatibility

Miglioramenti al protocollo TDS

SQL Server archivia i vettori in un formato binario ottimizzato, ma li espone come matrici JSON per praticità.

I driver supportati usano miglioramenti al protocollo TDS per trasmettere i dati vettoriali in modo più efficiente in formato binario e presentarli alle applicazioni come tipi vettoriali nativi. Questo approccio riduce le dimensioni del payload, elimina il sovraccarico dell'analisi JSON e mantiene la precisione a virgola mobile completa. Di conseguenza, migliora sia le prestazioni che l'accuratezza quando si lavora con vettori altamente dimensionali in scenari di intelligenza artificiale e machine learning.

Supporto del driver nativo

Le applicazioni che usano TDS versione 7.4 o successiva e i driver aggiornati possono leggere, scrivere, trasmettere e copiare in modo nativo i dati vettoriali in massa.

Queste funzionalità richiedono versioni dei driver seguenti. Assicurarsi di usare la versione corretta per abilitare il supporto del vettore nativo.

• Microsoft.Data.SqlClient: la versione 6.1.0 introduce il SqlVector tipo, estendendo System.Data.SqlDbTypes.
• Microsoft JDBC Driver per SQL Server: la versione 13.1.0 Preview introduce il microsoft.sql.Types.VECTOR tipo e microsoft.sql.Vector classe.

È possibile iniziare subito a usare il nuovo tipo di vettore . Gli esempi seguenti illustrano lingue e configurazioni del driver diverse.

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

Gli strumenti seguenti supportano il tipo di dati vector :

• SQL Server Management Studio versione 21 e versioni successive
• DacFX e SqlPackage versione 162.5 (novembre 2024) e versioni successive
• Estensione SQL Server per Visual Studio Code versione 1.32 (maggio 2025) e versioni successive
• Microsoft.Build.Sql versione 1.0.0 (marzo 2025) e versioni successive
• SQL Server Data Tools (Visual Studio 2022) versione 17.13 e versioni successive

Limitations

Il tipo di vettore presenta le limitazioni seguenti:

Tables

• I vincoli a livello di colonna non sono supportati, ad eccezione dei vincoli NULL e NOT NULL.

  • DEFAULT e i vincoli CHECK non sono supportati per le colonne vettoriali.

  • I vincoli di chiave, ad esempio PRIMARY KEY o FOREIGN KEY, non sono supportati per le colonne vettoriali . L'uguaglianza, l'univocità, i join che usano colonne vettoriali come chiavi e gli ordini di ordinamento non si applicano ai tipi di dati vettoriali .

  • Non esiste alcuna nozione di univocità per i vettori, quindi i vincoli univoci non sono applicabili.

  • Controllare l'intervallo di valori all'interno di un vettore non è applicabile.

• I vettori non supportano il confronto, l'addizione, la sottrazione, la moltiplicazione, la divisione, la concatenazione o qualsiasi altro operatore di assegnazione matematica, logica e composta.

• Non puoi usare colonne vettoriali in tabelle ottimizzate per la memoria.

Indexes

• Non puoi usare indici B-tree o indici columnstore sulle colonne vettoriali . Tuttavia, puoi includere una colonna vettoriale come colonna inclusa in una definizione di indice.
• Gli indici vettoriali creano un indice approssimato su una colonna vettoriale per migliorare le prestazioni della ricerca tra vicini più prossimi. Per saperne di più su come funzionano l'indicizzazione vettoriale e la ricerca vettoriale, e sulle differenze tra ricerca esatta e approssimativa, consulta Ricerca vettoriale e indici vettoriali nel SQL motore di database.

Metadati dello schema di tabella

• La stored procedure di sistema sp_describe_first_result_set non restituisce correttamente il tipo di dati vector. Di conseguenza, molti client e driver di accesso ai dati vedono un tipo di dato varchar o nvarchar .

Tabelle del libro mastro

• La procedura sp_verify_database_ledger memorizzata genera un errore se il database contiene una tabella con una colonna vettoriale .

Tipi definiti dall'utente

• Non è possibile creare un alias di tipo con CREATE TYPE per il tipo vector. Questa restrizione è simile al comportamento dei tipi di dati xml e json .

Sempre Crittografato

• Il tipo vector non è supportato dalla funzionalità Always Encrypted.

Problemi noti

• Il mascheramento dei dati attualmente mostra i dati vettoriali come tipo di dati varbinary nel portale di Azure.

Contenuti correlati

• Supporto per i floating point a mezza precisione nel tipo di dati vector
• Ricerca vettoriale e indici vettoriali nel motore di database SQL
• Applicazioni intelligenti
• Funzioni vettoriali