Jenis Data Vektor

Berlaku untuk: SQL Server 2025 (17.x) Azure SQL DatabaseAzure SQL Managed InstanceSQL database di Microsoft Fabric

Tipe data vektor menyimpan data vektor yang dioptimalkan untuk operasi seperti pencarian kesamaan dan aplikasi pembelajaran mesin. Vektor disimpan dalam format biner yang dioptimalkan tetapi diekspos sebagai array JSON untuk kenyamanan. Setiap elemen vektor disimpan sebagai nilai floating-point presisi tunggal (4-byte).

Untuk memberikan pengalaman yang familier bagi pengembang, jenis data vektor dibuat dan ditampilkan sebagai array JSON. Misalnya, vektor dengan tiga dimensi dapat direpresentasikan sebagai '[0.1, 2, 30]'. Konversi antara tipe vector dan tipe char, nchar, varchar, nvarchar, dan json dapat bersifat implisit atau eksplisit, di kedua arah. Konversi antara vektor dan semua tipe data lainnya tidak diperbolehkan. Konversi antara dua nilai vektor hanya diperbolehkan jika dimensi dan tipe dasar (float32 atau float16) sama; jika tidak, terjadi error 42204 atau error 42238.

Saat Anda mengonversi string atau nilai json menjadi vektor, nilainya harus berupa array angka JSON. Jumlah elemen harus sama dengan dimensi vektor; jika tidak, terjadi kesalahan 42204. Nilai lain menyebabkan kesalahan 13670. Spasi putih sebelum dan sesudah array diabaikan.

Ketika Anda mengonversi vektor menjadi tipe string, hasilnya menggunakan notasi ilmiah, misalnya [1.0000000e+000,2.5000000e+000,-3.0000000e+000]. Ketika Anda mengonversi vektor ke json, hasilnya menggunakan notasi desimal, misalnya [1.0000000000,2.5000000000,-3.0000000000]. Jika panjang target terlalu pendek, terjadi error 42211. Nilainya tidak terpotong.

vektor memiliki prioritas lebih rendah daripada tipe string. Dalam UNION, CASE, COALESCE, , dan ekspresi lain yang menggabungkan vektor dengan tipe string, hasilnya adalah tipe string.

Untuk informasi selengkapnya tentang bekerja dengan data vektor, lihat:

Contoh sintaks

Sintaks penggunaan untuk jenis vektor mirip dengan semua jenis data SQL Server lainnya dalam tabel.

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

Secara default, tipe dasarnya adalah float32. Untuk menggunakan half-precision, tentukan float16 secara eksplisit.

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

Dimensions

Vektor harus memiliki setidaknya satu dimensi. Jumlah maksimum dimensi tergantung pada tipe basis vektor:

  • float32 mendukung hingga 1.998 dimensi.
  • float16 mendukung hingga 3.996 dimensi.

Ketersediaan fitur

Tipe data vektor tersedia di semua tingkat kompatibilitas basis data. Jika Anda tidak menentukan tipe dasar, vektor menggunakan float32.

Fitur vektor tersedia di Azure SQL Managed Instance yang dikonfigurasi dengan kebijakan Always-up-to-date .

Vektor float16 presisi setengah

  • Vektor half-precision (float16) umumnya tersedia di Azure SQL Database, Azure SQL Managed Instance, dan database SQL di Microsoft Fabric. Tidak diperlukan konfigurasi pratinjau.

  • Di SQL Server 2025 (17.x), vektor setengah presisi (float16) tersedia dalam preview. Untuk menggunakan float16 di SQL Server 2025, Anda harus mengaktifkan PREVIEW_FEATURES opsi konfigurasi terbatas database. Untuk informasi lebih lanjut, lihat Aktifkan fitur pratinjau di SQL Server 2025.

Untuk informasi lebih lanjut tentang vektor setengah presisi, lihat Dukungan float setengah presisi dalam tipe data vektor.

Aktifkan fitur pratinjau di SQL Server 2025

Untuk beberapa fitur pratinjau di SQL Server 2025, Anda harus mengaktifkan PREVIEW_FEATURES opsi konfigurasi terbatas database.

ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;
GO

Untuk informasi lebih lanjut, lihat PREVIEW_FEATURES.

Examples

A. Definisi kolom

Gunakan tipe vektor dalam definisi kolom dalam sebuah CREATE TABLE pernyataan. Contohnya:

Contoh berikut membuat tabel dengan kolom vektor dan menyisipkan data ke dalamnya.

Definisikan kolom vektor dalam tabel dengan menggunakan tipe dasar default float32 atau float16 untuk penyimpanan setengah presisi.

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. Penggunaan dalam variabel

Contoh berikut mendeklarasikan vektor dengan menggunakan tipe data vektor baru dan menghitung jarak menggunakan fungsi tersebut VECTOR_DISTANCE .

Gunakan tipe vektor dengan variabel:

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. Penggunaan dalam prosedur atau fungsi tersimpan

Anda dapat menggunakan tipe data vektor sebagai parameter dalam prosedur atau fungsi tersimpan. Contohnya:

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

Conversions

  • Anda tidak bisa menggunakan tipe vektor dengan tipe sql_variant atau menetapkannya ke variabel atau kolom sql_variant . Pembatasan ini mirip dengan varchar(max), varbinary(max), nvarchar(max), xml, json, dan jenis data berbasis CLR.

Compatibility

Penyempurnaan protokol TDS

SQL Server menyimpan vektor dalam format biner yang dioptimalkan tetapi mengeksposnya sebagai array JSON untuk kenyamanan.

Driver yang didukung menggunakan penyempurnaan pada protokol TDS untuk mengirimkan data vektor secara lebih efisien dalam format biner dan menyajikannya ke aplikasi sebagai jenis vektor asli. Pendekatan ini mengurangi ukuran payload, menghilangkan overhead penguraian format JSON, dan mempertahankan presisi titik mengambang penuh. Akibatnya, ia meningkatkan performa dan akurasi saat bekerja dengan vektor dimensi tinggi dalam AI dan skenario pembelajaran mesin.

Dukungan Driver Asli

Aplikasi yang menggunakan TDS versi 7.4 atau lebih tinggi dan driver yang diperbarui dapat membaca, menulis, mengalirkan, dan menyalin data vektor secara massal secara asli.

Kemampuan ini memerlukan versi driver berikut. Pastikan Anda menggunakan versi yang benar untuk mengaktifkan dukungan vektor asli.

  • Microsoft.Data.SqlClient: Versi 6.1.0 memperkenalkan tipe baru, SqlVector, yang memperluas System.Data.SqlDbTypes.
  • Microsoft JDBC Driver untuk SQL Server: Versi 13.1.0 Pratinjau memperkenalkan microsoft.sql.Types.VECTOR tipe dan microsoft.sql.Vector kelas.

Note

Dukungan transpor biner asli untuk vektor float16 tersedia di Microsoft JDBC Driver 13.4 untuk SQL Server dan Microsoft ODBC Driver 18.7.1 untuk SQL Server. Driver ini menserialisasi dan mendeserialisasi nilai vektor setengah presisi menggunakan format kawat asli, sehingga mengurangi payload jaringan dibandingkan dengan representasi JSON. Gunakan versi driver ini atau yang lebih baru untuk dukungan native float16. Driver yang tidak mendukung transport float16 native dapat tetap bekerja dengan vektor yang direpresentasikan sebagai varchar(max) array JSON.

Note

Untuk klien yang tidak mendukung protokol TDS yang diperbarui, SQL Server terus mengekspos data vektor sebagai jenis varchar(max) untuk memastikan kompatibilitas mundur. Aplikasi klien dapat bekerja dengan data vektor seolah-olah itu adalah array JSON. SQL Database Engine secara otomatis mengonversi vektor ke dan dari array JSON, membuat jenis baru transparan untuk klien. Oleh karena itu driver dan semua bahasa secara otomatis kompatibel dengan jenis baru.

Anda dapat segera mulai menggunakan jenis vektor baru. Contoh berikut menunjukkan berbagai bahasa dan konfigurasi driver.

Important

Memerlukan Microsoft.Data.SqlClient 6.1.0 atau yang lebih baru untuk dukungan vektor asli.

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

Jika Anda tidak menggunakan driver .NET terbaru, Anda masih bisa bekerja dengan data vektor di C# dengan menyerialisasi dan mendeserialisasi sebagai string JSON menggunakan kelas tersebutJsonSerializer. Pendekatan ini memastikan kompatibilitas dengan representasi vektor varchar(max) yang disediakan oleh SQL Server bagi klien lama.

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

Alat berikut mendukung jenis data vektor :

Limitations

Jenis vektor memiliki batasan berikut:

Tables

  • Batasan level kolom tidak didukung, kecuali batasan NULL dan NOT NULL.

    • DEFAULT dan CHECK batasan tidak didukung untuk kolom vektor .

    • Batasan utama, seperti PRIMARY KEY atau FOREIGN KEY, tidak didukung untuk kolom vektor . Kesetaraan, keunikan, gabungan menggunakan kolom vektor sebagai kunci, dan urutan pengurutan tidak berlaku untuk jenis data vektor .

    • Tidak ada gagasan keunikan untuk vektor, sehingga batasan unik tidak berlaku.

    • Memeriksa rentang nilai dalam vektor tidak berlaku.

  • Vektor tidak mendukung perbandingan, penambahan, pengurangan, perkalian, pembagian, perangkaian, atau operator penugasan matematika, logis, dan majemuk lainnya.

  • Anda tidak bisa menggunakan kolom vektor dalam tabel yang dioptimalkan untuk memori.

Indexes

  • Anda tidak dapat menggunakan indeks B-tree atau indeks penyimpanan kolom pada kolom vektor. Namun, Anda dapat memasukkan kolom vektor sebagai kolom yang disertakan dalam definisi indeks.
  • Indeks vektor membuat indeks perkiraan pada kolom vektor untuk meningkatkan kinerja pencarian tetangga terdekat. Untuk mempelajari lebih lanjut tentang cara kerja pengindeksan vektor dan pencarian vektor, serta perbedaan antara pencarian eksak dan perkiraan, lihat Indeks pencarian vektor dan vektor di SQL Database Engine.

Metadata skema tabel

  • Prosedur tersimpan sistem sp_describe_first_result_set tidak mengembalikan tipe data vektor dengan benar. Akibatnya, banyak klien dan driver akses data melihat tipe data varchar atau nvarchar .

Tabel buku besar

  • Prosedur sp_verify_database_ledger tersimpan menghasilkan kesalahan jika database berisi tabel dengan kolom vektor .

Jenis yang ditentukan pengguna

  • Anda tidak bisa membuat tipe alias menggunakan CREATE TYPE untuk tipe vektor . Pembatasan ini mirip dengan perilaku tipe data xml dan json .

Selalu Terenkripsi

  • Tipe vektor tidak didukung dengan fitur Always Encrypted.

Masalah yang diketahui

  • Masking Data saat ini menunjukkan data vektor sebagai jenis data varbinary di portal Microsoft Azure.

Konten terkait

  • Terakhir diperbarui pada