Condividi tramite

Tipo di dati vettoriali

Si applica a: Sql Server 2025 (17.x) DatabaseSQL di Azure Istanza gestita di SQL di Azurein Microsoft Fabric

Il tipo di dati vector è progettato per archiviare i dati vettoriali ottimizzati per operazioni come la ricerca di somiglianza e le 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]'. È possibile eseguire la conversione implicita ed esplicita da e al tipo vector usando tipi varchar, nvarchar e json .

Note

SQL Server 2025 (17.x) supporta vettori a metà precisione (float16). Per ulteriori informazioni, vedere Supporto a virgola mobile a bassa precisione nel tipo di dati vettore.

float16 vector è attualmente disponibile per l'anteprima. Per testare, abilitare l'opzione PREVIEW_FEATURES di configurazione con ambito database. Per informazioni dettagliate, vedere PREVIEW_FEATURES = { ON | OFF }.

ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;
GO

Per le limitazioni, vedere Limitazioni e Problemi noti.

Note

Le funzionalità vettoriali sono disponibili in Istanza gestita di SQL di Azure configurata con il criterio [Always-up-to-date](/azure/azure-sql/managed-instance/ update-policy#always-up-to-date-update-policy).

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

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 ]

Per impostazione predefinita, il tipo di base è float32. Per usare la mezza precisione, è necessario specificare float16 in modo esplicito.

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

Dimensions

Un vettore deve avere almeno una dimensione. Il numero massimo di dimensioni supportate è 1998.

Examples

A. Definizione di colonna

Il tipo di vettore può essere usato nella definizione di colonna contenuta in un'istruzione CREATE TABLE , ad esempio:

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

È possibile definire una colonna vettoriale in una tabella usando il tipo di base predefinito (float32) o specificare float16 in modo esplicito per l'archiviazione a metà precisione.

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

CREATE TABLE dbo.vectors
(
    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

Nell'esempio seguente vengono dichiarati vettori usando il nuovo tipo di dati vector e vengono calcolate le distanze usando la VECTOR_DISTANCE funzione .

Il tipo di vettore può essere usato con le variabili:

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

C. Utilizzo in stored procedure o funzioni

Il tipo di dati vector può essere usato come parametro in 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

Disponibilità delle funzionalità

Il nuovo tipo di vettore è disponibile in tutti i livelli di compatibilità del database.

Il supporto per i vettori float16 è attualmente condizionato dalla configurazione PREVIEW_FEATURES. È necessario abilitarlo in modo esplicito prima di usare VECTOR(..., float16).

ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;
GO

Conversions

  • Il tipo di vettore non può essere usato con il tipo sql_variant o assegnato a una variabile o a una 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.

Note

float16 i vettori sono attualmente trasmessi come varchar(max) (matrice JSON) su TDS. Il supporto del trasporto binario per float16 non è ancora disponibile nei driver come ODBC, JDBC e .NET.

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.

Note

Per i client che non supportano il protocollo TDS aggiornato, SQL Server continua a esporre i dati vettoriali come tipi varchar(max) per garantire la compatibilità con le versioni precedenti. Le applicazioni client possono usare i dati vettoriali come se fossero una matrice JSON. Il motore di database SQL converte automaticamente i vettori in e da una matrice JSON, rendendo trasparente il nuovo tipo per il client. Di conseguenza, i driver e tutte le lingue sono automaticamente compatibili con il nuovo tipo.

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

Important

Richiede Microsoft.Data.SqlClient 6.1.0 o versione successiva per il supporto di vettori nativi.

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

Note

Se non si usano i driver .NET più recenti, è comunque possibile usare i dati vettoriali in C# serializzandoli e deserializzandoli come stringa JSON usando la JsonSerializer classe . Ciò garantisce la compatibilità con la varchar(max) rappresentazione dei vettori esposti da SQL Server per i client meno recenti.

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

Tools

Gli strumenti seguenti supportano il tipo di dati vector :

Limitations

Il tipo di vettore presenta le limitazioni seguenti:

Tables

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

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

    • Anche il controllo dell'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.

  • le colonne vettoriali non possono essere usate nelle tabelle ottimizzate per la memoria.

Indexes

  • Gli indici dell'albero B o gli indici columnstore non sono consentiti nelle colonne vettoriali . Tuttavia, una colonna vettoriale può essere specificata come colonna inclusa in una definizione di indice.

Metadati dello schema di tabella

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

Tabelle del libro mastro

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

Tipi definiti dall'utente

  • La creazione del tipo alias che usa CREATE TYPE per il tipo vector non è consentita, analogamente al comportamento dei tipi di dati xml e json .

Sempre Crittografato

  • il tipo vector non è supportato con la 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

  • Last updated on