Typ danych wektora

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

Typ danych wektorowych przechowuje dane wektorowe zoptymalizowane 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]'. Możesz niejawnie i jawnie przekonwertować między typem wektora a typami varchar, nvarchar i json .

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 typ bazowy to float32. Aby użyć półprecyzji, określ float16 wyraźnie.

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

Dimensions

Wektor musi mieć co najmniej jeden wymiar. Maksymalna liczba wymiarów zależy od typu bazy wektorowej:

  • Float32 obsługuje do 1 998 wymiarów.
  • Float16 obsługuje do 3 996 wymiarów.

Dostępność funkcji

Typ danych wektorowych jest dostępny na wszystkich poziomach zgodności bazy danych. Jeśli nie określisz typu bazowego, wektor używa float32.

Funkcje wektorowe są dostępne w usłudze Azure SQL Managed Instance skonfigurowane przy użyciu zasad Always-up-to-date .

Wektory float16 o półprecyzji

  • Wektory półprecyzyjne (float16) są zazwyczaj dostępne w Azure SQL Database, Azure SQL Managed Instance oraz bazie danych SQL w Microsoft Fabric. Nie jest wymagana konfiguracja podglądowa.

  • W SQL Server 2025 (17.x) wektory o półprecyzji (float16) są dostępne w podglądzie. Aby użyć float16 w SQL Server 2025, musisz włączyć PREVIEW_FEATURES opcję konfiguracji z zakresem bazy danych. Więcej informacji można znaleźć w artykule Włącz funkcje podglądowe w SQL Server 2025.

Więcej informacji o wektorach o półprecyzji można znaleźć w artykule Obsługa floatu o półprecyzji w typie danych wektorowych.

Włącz funkcje podglądowe w SQL Server 2025

Aby korzystać z niektórych funkcji w wersji zapoznawczej w programie SQL Server 2025, należy włączyć opcję konfiguracji w zakresie bazy danych PREVIEW_FEATURES.

ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;
GO

Więcej informacji można znaleźć w PREVIEW_FEATURES.

Examples

A. Definicja kolumny

Użyj typu vector w definicjach kolumn w instrukcji CREATE TABLE. Przykład:

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

Zdefiniuj kolumnę wektorową w tabeli, używając domyślnego typu bazy float32 lub float16 do przechowywania o półprecyzji.

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

Poniższy przykład deklaruje wektory używając nowego typu danych wektorowych i oblicza odległości za pomocą VECTOR_DISTANCE funkcji.

Użyj typu wektorowego z zmiennymi:

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. Zastosowanie w procedurach składowanych lub funkcjach

Możesz użyć typu danych wektorowego jako parametru w procedurach lub funkcjach przechowywanych. Przykład:

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

Conversions

  • Nie możesz użyć typu wektora razem z typem sql_variant ani przypisać go do zmiennej czy kolumny 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.

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

Natywny transport binarny dla wektorów float16 jest obsługiwany w Microsoft JDBC Driver 13.4 dla SQL Server oraz Microsoft ODBC Driver 18.7.1 dla SQL Server. Sterowniki te serializują i deserializują wartości wektorowe o półprecyzji, używając natywnego formatu przewodowego, zmniejszając obciążenie sieciowe w porównaniu do reprezentacji JSON. Należy używać tych wersji sterowników lub nowszych wersji do natywnego przesyłania float16. Sterowniki, które nie obsługują natywnego transportu float16 , mogą nadal pracować z wektorami reprezentowanymi jako varchar(max) macierze JSON.

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 .NET, nadal możesz pracować z danymi wektorowymi w C#, serializując i deserializując je jako ciąg JSON za pomocą tej klasyJsonSerializer. Takie podejście zapewnia kompatybilność z reprezentacją varchar(max) wektorów, którą SQL Server udostępnia starszym klientom.

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 kolumn nie są obsługiwane, z wyjątkiem ograniczeń NULL i NOT NULL.

    • 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 obrębie wektora 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ń.

  • Nie można używać kolumn wektorowych w tabelach zoptymalizowanych pod pamięć.

Indexes

  • Nie można używać indeksów B-drzewa ani indeksów magazynu kolumnowego na kolumnach wektor. Jednak możesz uwzględnić kolumnę wektorową jako kolumnę zawartą w definicji indeksu.
  • Indeksy wektorowe tworzą przybliżony indeks w kolumnie wektorowej, aby poprawić wydajność wyszukiwania najbliższych sąsiadów. Aby dowiedzieć się więcej o tym, jak działa indeksowanie wektorowe i wyszukiwanie wektorowe oraz jakie są różnice między wyszukiwaniem dokładnym a przybliżonym, zobacz wyszukiwanie wektorowe i indeksy wektorowe w SQL Database Engine.

Metadane schematu tabeli

  • Procedura przechowywana w sp_describe_first_result_set systemie nie zwraca poprawnie typu danych wektorowych . W rezultacie wielu klientów i sterowników dostępu do danych widzi typ danych varchar lub nvarchar .

Tabele rejestru

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

Typy zdefiniowane przez użytkownika

  • Nie można utworzyć typu aliasowego przy użyciu CREATE TYPE dla typu vector. To ograniczenie jest podobne do zachowania typów danych xml i json .

Zawsze szyfrowane

  • Typ vector nie jest obsługiwany przez funkcję Always Encrypted.

Znane problemy

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

Treści powiązane

  • Ostatnia aktualizacja o