Udostępnij za pomocą

Typ danych wektora

Dotyczy: SQL Server 2025 (17.x) Azure SQL DatabaseAzure SQL Managed InstanceSQL Database w usłudze Microsoft Fabric

Typ danych wektorów jest przeznaczony do przechowywania danych wektorowych zoptymalizowanych pod kątem operacji, takich jak wyszukiwanie podobieństwa i aplikacje uczenia maszynowego. Wektory są przechowywane w zoptymalizowanym formacie binarnym, ale są uwidocznione jako tablice JSON dla wygody. Każdy element wektora jest przechowywany jako wartość zmiennoprzecinkowa o pojedynczej precyzji (4 bajtów).

Aby zapewnić znajome doświadczenie deweloperom, typ danych wektor jest tworzony i wyświetlany jako tablica JSON. Na przykład wektor z trzema wymiarami może być reprezentowany jako '[0.1, 2, 30]'. Niejawną i jawną konwersję na i z typu wektora można wykonać przy użyciu typów varchar, nvarchar i json.

Note

Program SQL Server 2025 (17.x) obsługuje wektory o połowie precyzji (float16). Aby uzyskać więcej informacji, zobacz Obsługa zmiennoprzecinkowa o połowie precyzji w typie danych wektorowych.

float16 wektor jest obecnie dostępny dla wersji zapoznawczej. Aby przetestować, włącz PREVIEW_FEATURES opcję konfiguracji z zakresem dla bazy danych. Aby uzyskać szczegółowe informacje, przejrzyj PREVIEW_FEATURES = { ON | WYŁĄCZONE }.

ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;
GO

Aby uzyskać informacje o ograniczeniach, zapoznaj się z tematem Ograniczenia i znane problemy.

Note

Funkcje wektorowe są dostępne w usłudze Azure SQL Managed Instance, skonfigurowanej przy użyciu zasad [Always-up-to-date](/azure/azure-sql/managed-instance/update-policy#always-up-to-date-update-policy).

Aby uzyskać więcej informacji na temat pracy z danymi wektorowymi, zobacz:

Przykładowa składnia

Składnia użycia typu wektor jest podobna do wszystkich innych typów danych w SQL Server w tabeli.

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

Domyślnie podstawowy typ to float32. Aby użyć połowy precyzji, należy jawnie określić float16 .

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

Dimensions

Wektor musi mieć co najmniej jeden wymiar. Maksymalna liczba obsługiwanych wymiarów to 1998.

Examples

A. Definicja kolumny

Typ wektora można używać w definicji kolumny zawartej w instrukcji CREATE TABLE, na przykład:

Poniższy przykład tworzy tabelę z kolumną wektorową i wstawia do niej dane.

Kolumnę wektorową można zdefiniować w tabeli przy użyciu domyślnego typu podstawowego (float32) lub jawnie określić float16 dla pamięci o połowicznej precyzji.

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. Użycie w zmiennych

Poniższy przykład deklaruje wektory przy użyciu nowego typu danych wektorów i oblicza odległości przy użyciu VECTOR_DISTANCE funkcji .

Typ wektora może być używany ze zmiennymi:

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

C. Zastosowanie w procedurach składowanych lub funkcjach

Typ danych wektor może być używany jako parametr w procedurze składowanej lub funkcji. Przykład:

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

Dostępność funkcji

Nowy typ wektora jest dostępny we wszystkich poziomach zgodności bazy danych.

float16 Obsługa wektorów jest obecnie blokowana w PREVIEW_FEATURES ramach konfiguracji. Musisz jawnie ją włączyć przed użyciem VECTOR(..., float16).

ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;
GO

Conversions

  • Typu wektora nie można używać z typem sql_variant, ani przypisywać do zmiennej lub kolumny typu sql_variant. To ograniczenie jest podobne do varchar(max), varbinary(max), nvarchar(max), xml, json i typów danych opartych na CLR.

Compatibility

Ulepszenia protokołu TDS

Program SQL Server przechowuje wektory w zoptymalizowanym formacie binarnym, ale uwidacznia je jako tablice JSON dla wygody.

Obsługiwane sterowniki używają ulepszeń protokołu TDS, aby wydajniej przesyłać dane wektorowe w formacie binarnym i prezentować je aplikacjom jako natywne typy wektorów. Takie podejście zmniejsza rozmiar ładunku, eliminuje obciążenie analizowania JSON i zachowuje pełną precyzję zmiennoprzecinkową. W rezultacie zwiększa wydajność i dokładność podczas pracy z wektorami o wysokim wymiarach w scenariuszach sztucznej inteligencji i uczenia maszynowego.

Note

float16 wektory są obecnie przesyłane jako varchar(max) (tablica JSON) za pośrednictwem TDS. Obsługa float16 transportu binarnego nie jest jeszcze dostępna w sterownikach, takich jak ODBC, JDBC i .NET.

Wbudowana obsługa sterowników

Aplikacje korzystające z TDS w wersji 7.4 lub nowszej i zaktualizowane sterowniki mogą natywnie odczytywać, zapisywać, strumieniowo i zbiorczo kopiować dane wektorów.

Te możliwości wymagają wersji następujących sterowników. Upewnij się, że używasz poprawnej wersji, aby włączyć obsługę wektorów natywnych.

  • Microsoft.Data.SqlClient: wersja 6.1.0 wprowadza typ SqlVector, rozszerzając System.Data.SqlDbTypes.
  • Sterownik JDBC firmy Microsoft dla programu SQL Server: wersja 13.1.0 (wersja zapoznawcza) wprowadza typ i microsoft.sql.Types.VECTOR klasęmicrosoft.sql.Vector.

Note

W przypadku klientów, którzy nie obsługują zaktualizowanego protokołu TDS, program SQL Server nadal uwidacznia dane wektorowe jako typy varchar(max), aby zapewnić zgodność z poprzednimi wersjami. Aplikacje klienckie mogą pracować z danymi wektorowymi tak, jakby były tablicą JSON. Silnik bazy danych SQL automatycznie konwertuje wektory na i z tablicy JSON, dzięki czemu nowy typ jest przejrzysty dla klienta. W związku z tym sterowniki i wszystkie języki są automatycznie zgodne z nowym typem.

Możesz zacząć od razu używać nowego typu wektora . W poniższych przykładach przedstawiono różne języki i konfiguracje sterowników.

Important

Wymaga programu Microsoft.Data.SqlClient 6.1.0 lub nowszego w celu obsługi wektorów natywnych.

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

Jeśli nie używasz najnowszych sterowników platformy .NET, nadal możesz pracować z danymi wektorowymi w języku C#, serializując i deserializując je jako ciąg JSON przy użyciu JsonSerializer klasy . Zapewnia to zgodność z reprezentacją varchar(max) wektorów uwidocznionych przez program SQL Server dla starszych klientów.

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

Następujące narzędzia obsługują typ danych wektorowych :

Limitations

Typ wektora ma następujące ograniczenia:

Tables

  • Ograniczenia na poziomie kolumny nie są obsługiwane, z wyjątkiem NULL/NOT NULL ograniczeń.

    • DEFAULT i CHECK ograniczenia nie są obsługiwane dla kolumn typu wektor.

    • Ograniczenia klucza, takie jak PRIMARY KEY lub FOREIGN KEY, nie są obsługiwane w przypadku kolumn wektorowych . Równość, unikatowość, sprzężenia używające kolumn wektorowych jako kluczy i kolejności sortowania nie mają zastosowania do typów danych wektorowych .

    • Nie ma pojęcia unikatowości dla wektorów, więc unikatowe ograniczenia nie mają zastosowania.

    • Sprawdzanie zakresu wartości w wektorze również nie ma zastosowania.

  • Wektory nie obsługują porównywania, dodawania, odejmowania, mnożenia, dzielenia, łączenia ani innych operatorów matematycznych, logicznych i złożonych przypisań.

  • kolumn wektorowych nie można używać w tabelach zoptymalizowanych pod kątem pamięci.

Indexes

  • Indeksy drzewa B lub indeksy kolumnowe nie są dozwolone w kolumnach wektor. Można jednak określić kolumnę wektorową jako dołączona kolumna w definicji indeksu.

Metadane schematu tabeli

  • sp_describe_first_result_set systemowa procedura składowana nie zwraca poprawnie typu danych wektorowych . W związku z tym wiele klientów i sterowników dostępu do danych widzi typ danych varchar lub nvarchar .

Tabele rejestru

  • Procedura sp_verify_database_ledger składowana generuje błąd, jeśli baza danych zawiera tabelę z kolumną wektorową .

Typy zdefiniowane przez użytkownika

  • Tworzenie typu aliasu przy użyciu CREATE TYPE dla typu wektor nie jest dozwolone, podobnie jak zachowaniu typów danych xml i json.

Zawsze szyfrowane

  • typ wektora nie jest obsługiwany z funkcją Always Encrypted.

Znane problemy

  • Maskowanie danych obecnie pokazuje dane wektorowe jako typ danych varbinary w portalu Azure.

Treści powiązane

  • Last updated on