Vectorgegevenstype

Van toepassing op: SQL Server 2025 (17.x) Azure SQL DatabaseAzure SQL Managed InstanceSQL-database in Microsoft Fabric

Het vectordatatype slaat vectorgegevens op die geoptimaliseerd zijn voor operaties zoals similarity search en machine learning-toepassingen. Vectoren worden opgeslagen in een geoptimaliseerde binaire indeling, maar worden voor het gemak weergegeven als JSON-matrices. Elk element van de vector wordt opgeslagen als een drijvende-kommawaarde met enkelvoudige precisie (4 bytes).

Voor een vertrouwde ervaring voor ontwikkelaars wordt het vectorgegevenstype gemaakt en weergegeven als een JSON-matrix. Een vector met drie dimensies kan bijvoorbeeld worden weergegeven als '[0.1, 2, 30]'. Je kunt impliciet en expliciet converteren tussen het vectortype en varchar-, nvarchar- en json-types .

Zie voor meer informatie over het werken met vectorgegevens:

Voorbeeldsyntaxis

De gebruiksyntaxis voor het vectortype is vergelijkbaar met alle andere SQL Server-gegevenstypen in een tabel.

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

Standaard is het basistype float32. Om halfprecisie te gebruiken, specificeer expliciet float16 .

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

Dimensions

Een vector moet ten minste één dimensie hebben. Het maximale aantal dimensies hangt af van het type vectorbasis:

  • float32 ondersteunt tot 1.998 dimensies.
  • float16 ondersteunt tot 3.996 dimensies.

Beschikbaarheid van functies

Het vectordatatype is beschikbaar onder alle databasecompatibiliteitsniveaus. Als je geen basistype specificeert, gebruikt de vector float32.

Vectorfuncties zijn beschikbaar in Azure SQL Managed Instance dat is geconfigureerd met het beleid Always-up-to-date .

Vectoren met halve precisie (float16)

  • Half-precision (float16) vectoren zijn over het algemeen beschikbaar in Azure SQL Database, Azure SQL Managed Instance en SQL database in Microsoft Fabric. Er is geen previewconfiguratie vereist.

  • In SQL Server 2025 (17.x) zijn half-precision (float16) vectoren beschikbaar in de preview. Om float16 te gebruiken in SQL Server 2025, moet je de PREVIEW_FEATURES optie voor databasescoped configuratie inschakelen. Voor meer informatie, zie Voorbeeldfuncties inschakelen in SQL Server 2025.

Raadpleeg voor meer informatie over half-precisievectoren Ondersteuning voor half-precision floats in het vectordatatype.

Schakel previewfuncties in SQL Server 2025 in

Voor sommige previewfuncties in SQL Server 2025 moet je de PREVIEW_FEATURES configuratieoptie voor databasescoped inschakelen.

ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;
GO

Voor meer informatie, zie PREVIEW_FEATURES.

Examples

A. Kolomdefinitie

Gebruik het vectortype in kolomdefinities binnen een CREATE TABLE statement. Voorbeeld:

In het volgende voorbeeld wordt een tabel met een vectorkolom gemaakt en worden er gegevens in ingevoegd.

Definieer een vectorkolom in een tabel door het standaard basistype float32 of float16 te gebruiken voor half-nauwkeurige opslag.

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. Gebruik in variabelen

Het volgende voorbeeld declareert vectoren met behulp van het nieuwe vectordatatype en berekent afstanden met behulp van de VECTOR_DISTANCE functie.

Gebruik het vectortype met variabelen:

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. Gebruik in opgeslagen procedures of functies

Je kunt het vectordatatype als parameter gebruiken in opgeslagen procedures of functies. Voorbeeld:

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

Conversions

  • Je kunt het vectortype niet gebruiken met het sql_variant type of het toewijzen aan een sql_variant variabele of kolom. Deze beperking is vergelijkbaar met varchar(max), varbinary(max), nvarchar(max), xml, json en CLR-gegevenstypen.

Compatibility

Verbeteringen aan het TDS-protocol

SQL Server slaat vectoren op in een geoptimaliseerde binaire indeling, maar maakt ze beschikbaar als JSON-matrices voor het gemak.

Ondersteunde stuurprogramma's gebruiken verbeteringen in het TDS-protocol om vectorgegevens efficiënter in binaire indeling te verzenden en deze als systeemeigen vectortypen aan toepassingen te presenteren. Deze aanpak vermindert de payloadgrootte, elimineert de overhead van JSON-parsering en behoudt volle floating-point precisie. Hierdoor worden zowel de prestaties als de nauwkeurigheid verbeterd bij het werken met high-dimensionale vectoren in AI- en machine learning-scenario's.

Ondersteuning voor systeemeigen stuurprogramma's

Toepassingen die gebruikmaken van TDS versie 7.4 of hoger en bijgewerkte stuurprogramma's kunnen systeemeigen vectorgegevens lezen, schrijven, streamen en bulksgewijs kopiëren.

Voor deze mogelijkheden zijn versies van de volgende stuurprogramma's vereist. Zorg ervoor dat u de juiste versie gebruikt om systeemeigen vectorondersteuning in te schakelen.

  • Microsoft.Data.SqlClient: versie 6.1.0 introduceert het SqlVector type uitbreiding System.Data.SqlDbTypes.
  • Microsoft JDBC-stuurprogramma voor SQL Server: versie 13.1.0 Preview introduceert het microsoft.sql.Types.VECTOR type en de microsoft.sql.Vector klasse.

Note

Native binair transport voor float16-vectoren wordt ondersteund in Microsoft JDBC Driver 13.4 voor SQL Server en Microsoft ODBC Driver 18.7.1 voor SQL Server. Deze drivers serialiseren en deserialiseren half-precisie vectorwaarden met behulp van het native wire-formaat, waardoor de netwerkpayload wordt verminderd ten opzichte van de JSON-representatie. Gebruik deze driverversies of hoger voor native float16-overdracht. Drivers die geen native float16-transport ondersteunen, kunnen blijven werken met vectoren die als varchar(max) JSON-arrays worden weergegeven.

Note

Voor clients die het bijgewerkte TDS-protocol niet ondersteunen, blijft SQL Server vectorgegevens beschikbaar maken als varchar(max) -typen om compatibiliteit met eerdere versies te garanderen. Clienttoepassingen kunnen werken met vectorgegevens alsof het een JSON-matrix is. De SQL Database Engine converteert automatisch vectoren van en naar een JSON-matrix, waardoor het nieuwe type transparant is voor de client. Daarom zijn stuurprogramma's en alle talen automatisch compatibel met het nieuwe type.

U kunt het nieuwe vectortype meteen gaan gebruiken. In de volgende voorbeelden ziet u verschillende talen en stuurprogrammaconfiguraties.

Important

Hiervoor is Microsoft.Data.SqlClient 6.1.0 of hoger vereist voor systeemeigen vectorondersteuning.

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

Als je niet de nieuwste .NET-drivers gebruikt, kun je nog steeds met vectordata in C# werken door het te serialiseren en te deserialiseren als een JSON-string met behulp van de JsonSerializer klasse. Deze aanpak zorgt voor compatibiliteit met de varchar(max)-weergave van vectoren die SQL Server beschikbaar stelt voor oudere clients.

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

De volgende hulpprogramma's ondersteunen het gegevenstype vector :

Limitations

Het vectortype heeft de volgende beperkingen:

Tables

  • Beperkingen op kolomniveau worden niet ondersteund, behalve de beperkingen NOT NULL en NULL.

    • DEFAULT en CHECK beperkingen worden niet ondersteund voor vectorkolommen .

    • Belangrijke beperkingen, zoals PRIMARY KEY of FOREIGN KEY, worden niet ondersteund voor vectorkolommen . Gelijkheid, uniekheid, joins met behulp van vectorkolommen als sleutels en sorteervolgordes zijn niet van toepassing op vectorgegevenstypen .

    • Er is geen idee van uniekheid voor vectoren, dus unieke beperkingen zijn niet van toepassing.

    • Het controleren van het bereik van waarden binnen een vector is niet van toepassing.

  • Vectoren bieden geen ondersteuning voor vergelijkingen, optellen, aftrekken, vermenigvuldigen, delen, samenvoegen of andere rekenkundige, logische en samengestelde toewijzingsoperatoren.

  • Je kunt geen vectorkolommen gebruiken in geheugengeoptimaliseerde tabellen.

Indexes

  • Je kunt geen B-boomindexen of kolomopslagindexen gebruiken op vectorkolommen . Je kunt echter ook een vectorkolom opnemen als een opgenomen kolom in een indexdefinitie.
  • Vectorindexen creëren een benaderende index op een vectorkolom om de prestaties van de zoekopdracht bij dichtstbijzijnde buren te verbeteren. Voor meer informatie over hoe vectorindexering en vectorzoekopdracht werken, en de verschillen tussen exacte en benaderende zoek, zie Vector search en vectorindexen in de SQL Database Engine.

Metagegevens van tabelschema

  • De sp_describe_first_result_set systeemopslagprocedure geeft het vectordatatype niet correct terug. Als gevolg hiervan zien veel clients en stuurprogramma's voor gegevenstoegang het gegevenstype varchar of nvarchar.

Grootboektabellen

  • De opgeslagen procedure sp_verify_database_ledger genereert een fout als de database een tabel met een vectorkolom bevat.

Door de gebruiker gedefinieerde typen

  • Je kunt geen aliastype maken met CREATE TYPE voor het type vector. Deze beperking lijkt op het gedrag van de xml - en json-datatypes .

Altijd versleuteld

  • Het vectortype wordt niet ondersteund met de Always Encrypted functie.

Bekende problemen

  • Gegevensmaskering toont momenteel vectorgegevens als varbinair gegevenstype in Azure Portal.

Verwante inhoud

  • Laatst bijgewerkt om