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]'. Konwersja między typem vector a typami char, nchar, varchar, nvarchar i json może być zarówno domyślna, jak i jawna, w obu kierunkach. Konwersja między wektorem a innymi typami danych jest zabroniona. Konwersja między dwoma wartościami wektorowymi jest dozwolona tylko wtedy, gdy wymiary i typ bazowy (float32 lub float16) są takie samo; w przeciwnym razie występuje błąd 42204 lub błąd 42238.

Gdy konwertujesz wartość ciągu lub json na wektor, wartość ta musi być tablicą JSON zawierającą liczby. Liczba elementów musi być równa wymiarom wektorowym; w przeciwnym razie występuje błąd 42204. Inne wartości powodują błąd 13670. Biała przestrzeń przed i po tablicy jest ignorowana.

Gdy przekształcasz wektor na typ ciągu znaków, wynik wykorzystuje notację naukową, na przykład [1.0000000e+000,2.5000000e+000,-3.0000000e+000]. Gdy konwertujesz wektor na json, wynik używa notacji dziesiętnej, na przykład [1.0000000000,2.5000000000,-3.0000000000]. Jeśli długość docelowa jest zbyt krótka, pojawia się błąd 42211. Wartość nie jest obcięta.

wektor ma niższy priorytet niż typy ciągów znaków. W UNION, CASE, COALESCE oraz innych wyrażeniach łączących vector z typem ciągu znaków wynikiem jest typ ciągu.

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

• Wyszukiwanie wektorowe i indeksy wektorowe w silniku bazy danych SQL
• Inteligentne aplikacje

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 liczb zmiennoprzecinkowych 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.

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

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

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

• SQL Server Management Studio w wersji 21 lub nowszej
• DacFX i SqlPackage w wersji 162.5 (listopad 2024) i nowszych wersjach
• Rozszerzenie programu SQL Server dla programu Visual Studio Code w wersji 1.32 (maj 2025 r.) i nowszych wersjach
• Microsoft.Build.Sql w wersji 1.0.0 (marzec 2025 r.) i nowszych wersjach
• SQL Server Data Tools (Visual Studio 2022) w wersji 17.13 lub nowszej

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

• Obsługa zmiennoprzecinkowa o połowie precyzji w typie danych wektorowych
• Wyszukiwanie wektorowe i indeksy wektorowe w silniku bazy danych SQL
• Inteligentne aplikacje
• Funkcje wektorowe