Vektör veri türü

Şunlar için geçerlidir: SQL Server 2025 (17.x) Azure SQL VeritabanıAzure SQL Yönetilen ÖrneğiMicrosoft Fabric'te SQL veritabanı

Vektör veri tipi, benzerlik arama ve makine öğrenimi uygulamaları gibi işlemler için optimize edilmiş vektör verilerini depolar. Vektörler iyileştirilmiş ikili biçimde depolanır ancak kolaylık sağlamak için JSON dizileri olarak kullanıma sunulur. Vektördeki her öğe tek duyarlıklı (4 bayt) kayan nokta değeri olarak depolanır.

Geliştiricilere tanıdık bir deneyim sağlamak için vektör veri türü oluşturulur ve JSON dizisi olarak görüntülenir. Örneğin, üç boyutlu bir vektör olarak '[0.1, 2, 30]'temsil edilebilir. Vektör tipi ile char, nchar, varchar, nvarchar ve json türleri arasındaki dönüşüm, her iki yönde de örtük veya açık olabilir. Vektör ile diğer tüm veri türleri arasında dönüşüm yasaktır. İki vektör değeri arasında dönüşüm yalnızca boyutlar ve temel tip (float32 veya float16) aynı olduğunda izin verilir; aksi takdirde, 42204 veya 42238 hatası meydana gelir.

Bir dizeyi veya json değerini vektöre dönüştürdüğünüzde, değer sayılardan oluşan bir JSON dizisi olmalıdır. Eleman sayısı vektör boyutlarına eşit olmalıdır; aksi takdirde, 42204 hatası meydana gelir. Diğer değerler 13670 hatası oluşturur. Diziden önce ve sonra beyaz boşluk göz ardı edilir.

Vektörü bir dize türüne dönüştürdüğünüzde, sonuç bilimsel bir gösterim kullanır, örneğin [1.0000000e+000,2.5000000e+000,-3.0000000e+000]. vector'u json'a dönüştürdüğünüzde, sonuç ondalık gösterim kullanır, örneğin [1.0000000000,2.5000000000,-3.0000000000]. Hedef uzunluğu çok kısa, 42211 hatası oluşur. Değer kırpılmamıştır.

vektör , dize tiplerine göre daha düşük önceliğe sahiptir. UNION, CASE, COALESCE ve vector'ü bir dize türüyle birleştiren diğer ifadelerde sonuç dize türüdür.

Vektör verileriyle çalışma hakkında daha fazla bilgi için bkz:

Örnek söz dizimi

vektör türü için kullanım söz dizimi, tablodaki diğer tüm SQL Server veri türlerine benzer.

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

Varsayılan olarak, temel tip float32'dir. Yarı hassasiyet kullanmak için float16'yı açıkça belirtin.

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

Dimensions

Vektör en az bir boyuta sahip olmalıdır. Boyutların maksimum sayısı vektör taban tipine bağlıdır:

  • float32 , 1.998 boyuta kadar destekler.
  • float16 , 3.996 boyuta kadar destekler.

Özellik kullanılabilirliği

Vektör veri tipi tüm veritabanı uyumluluk seviyelerinde mevcuttur. Bir baz tipi belirtmiyorsanız, vektör float32 kullanır.

Vektör özellikleri, Always-up-to-date ilkesiyle yapılandırılmış Azure SQL Yönetilen Örneği'nde kullanılabilir.

Yarı hassasiyetli float16 vektörleri

  • Yarı hassasiyetli (float16) vektörler genellikle Azure SQL Veritabanı, Azure SQL Yönetilen Örneği ve Microsoft Fabric'te SQL database içinde mevcuttur. Önizleme yapılandırması gerekmez.

  • SQL Server 2025 (17.x)'de yarı hassasiyetli (float16) vektörler önizleme olarak mevcuttur. SQL Server 2025'te float16'yı kullanmak için veritabanı kapsamlı yapılandırma seçeneğini etkinleştirmeniz PREVIEW_FEATURES gerekir. Daha fazla bilgi için, SQL Server 2025'te önizleme özelliklerini etkinleştir bölümüne bakınız.

Yarım hassasiyetli vektörler hakkında daha fazla bilgi için bkz. Vektör veri tipinde yarı hassasiyetli float desteği.

SQL Server 2025'te önizleme özelliklerini etkinleştir

SQL Server 2025'teki bazı önizleme özellikleri için, veritabanı kapsamlı yapılandırma seçeneğini etkinleştirmeniz PREVIEW_FEATURES gerekir.

ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;
GO

Daha fazla bilgi için bkz. PREVIEW_FEATURES.

Examples

A. Sütun tanımı

Bir CREATE TABLE ifade içindeki sütun tanımlarında vektör tipini kullanın. Örneğin:

Aşağıdaki örnek, vektör sütunu olan bir tablo oluşturur ve içine veri ekler.

Bir tabloda bir vektör sütununu varsayılan temel tipi float32 veya float16 kullanarak yarı hassasiyet depolama için tanımlayın.

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. Değişkenlerde kullanım

Aşağıdaki örnek, yeni vektör veri tipi kullanılarak vektörleri ilan eder ve fonksiyon kullanılarak mesafeleri VECTOR_DISTANCE hesaplar.

Değişkenli vektör tipini kullanın:

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. Saklı yordamlarda veya işlevlerde kullanım

Vektör veri tipini depolanmış prosedürlerde veya fonksiyonlarda parametre olarak kullanabilirsiniz. Örneğin:

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

Conversions

  • Vektör tipini sql_variant tipiyle kullanamazsınız veya sql_variant değişken veya sütuna atamazsınız. Bu kısıtlama varchar(max), varbinary(max), nvarchar(max), xml, json ve CLR tabanlı veri türlerine benzer.

Compatibility

TDS protokolü geliştirmeleri

SQL Server, vektörleri iyileştirilmiş ikili biçimde depolar ancak kolaylık sağlamak için bunları JSON dizileri olarak kullanıma sunar.

Desteklenen sürücüler, vektör verilerini ikili biçimde daha verimli bir şekilde iletmek ve bunları yerel vektör türleri olarak uygulamalara sunmak için TDS protokolünde yapılan geliştirmeleri kullanır. Bu yaklaşım yük boyutunu azaltır, JSON ayrıştırma yükünü ortadan kaldırır ve tam kayan nokta duyarlığı korur. Sonuç olarak, yapay zeka ve makine öğrenmesi senaryolarında yüksek boyutlu vektörlerle çalışırken hem performansı hem de doğruluğu artırır.

Yerel Sürücü Desteği

TDS sürüm 7.4 veya üzeri ve güncelleştirilmiş sürücüleri kullanan uygulamalar vektör verilerini yerel olarak okuyabilir, yazabilir, akışla aktarabilir ve toplu olarak kopyalayabilir.

Bu özellikler aşağıdaki sürücülerin sürümlerini gerektirir. Yerel vektör desteğini etkinleştirmek için doğru sürümü kullandığınızdan emin olun.

  • Microsoft.Data.SqlClient: 6.1.0 sürümü, SqlVector türünü genişleten System.Data.SqlDbTypes öğesini tanıtıyor.
  • SQL Server için Microsoft JDBC Sürücüsü: Sürüm 13.1.0 Önizleme türü ve sınıfı tanıtır.

Note

Float16 vektörleri için yerel ikili taşıma, Microsoft JDBC Driver 13.4 for SQL Server ve Microsoft ODBC Driver 18.7.1 for SQL Server tarafından desteklenmektedir. Bu sürücüler, yarı hassasiyetli vektör değerlerini yerel wire formatını kullanarak serileştirir ve seri durumdan çözer; böylece JSON temsiline kıyasla ağ yükünü azaltır. Yerel float16 aktarımı için bu sürücü sürümlerini veya daha yenilerini kullanın. Yerel float16 taşımasını desteklemeyen sürücüler, JSON dizileri olarak varchar(max) temsil edilen vektörlerle çalışmaya devam edebilir.

Note

Güncelleştirilmiş TDS protokollerini desteklemeyen istemciler için SQL Server, geriye dönük uyumluluk sağlamak için vektör verilerini varchar(max) türleri olarak kullanıma açmaya devam eder. İstemci uygulamaları vektör verileriyle bir JSON dizisiymiş gibi çalışabilir. SQL Veritabanı Altyapısı, vektörleri otomatik olarak bir JSON dizisine dönüştürür ve yeni türü istemci için saydam hale getirir. Bu nedenle sürücüler ve tüm diller yeni türle otomatik olarak uyumludur.

Yeni vektör türünü hemen kullanmaya başlayabilirsiniz. Aşağıdaki örneklerde farklı diller ve sürücü yapılandırmaları gösterilmektedir.

Important

Yerel vektör desteği için Microsoft.Data.SqlClient 6.1.0 veya üzeri gerekir.

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

En son .NET sürücülerini kullanmıyorsanız, JsonSerializer sınıfını kullanarak vektör verileriyle C#'ta bunları JSON dizesi olarak serileştirip serileştirmesini çözerek yine de çalışabilirsiniz. Bu yaklaşım, SQL Server'ın eski istemciler için ortaya çıkardığı vektörlerin temsili ile varchar(max) uyumluluğu sağlar.

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

Aşağıdaki araçlar vektör veri türünü destekler:

Limitations

Vektör türü aşağıdaki sınırlamalara sahiptir:

Tables

  • Sütun seviyesindeki kısıtlamalar desteklenmez, sadece NULL ve NOT NULL için geçerlidir.

    • DEFAULT ve CHECK kısıtlamaları vektör sütunları için desteklenmez.

    • veya PRIMARY KEYgibi FOREIGN KEY temel kısıtlamalar vektör sütunları için desteklenmez. Eşitlik, benzersizlik, vektör sütunlarını anahtar olarak kullanan birleşimler ve sıralama düzenleri vektör veri türlerine uygulanmaz.

    • Vektörler için benzersizlik diye bir şey yoktur, bu nedenle benzersiz kısıtlamalar geçerli değildir.

    • Bir vektör içindeki değer aralığını kontrol etmek geçerli değildir.

  • Vektörler karşılaştırmayı, toplamayı, çıkarmayı, çarpmayı, bölmeyi, birleştirmeyi veya diğer matematik, mantıksal ve bileşik atama işleçlerini desteklemez.

  • Vektör sütunlarını bellek optimize edilmiş tablolarda kullanamazsınız.

Indexes

  • Vektör sütunlarında B-tree indekslerini veya columnstore indekslerini kullanamazsınız. Ancak, bir indeks tanımında bir vektör sütunu dahil edilen sütun olarak da dahil edebilirsiniz.
  • Vektör indeksleri, en yakın komşu aramasının performansını artırmak için bir vektör sütununda yaklaşık bir indeks oluşturur. Vektör indeksleme ve vektör aramasının nasıl çalıştığı ve kesin ile yaklaşık arama arasındaki farklar hakkında daha fazla bilgi edinmek için SQL Database Engine'deki Vektör arama ve vektör indekslerine bakınız.

Tablo şeması meta verileri

  • sp_describe_first_result_set sistem depolanmış prosedür vektör veri tipini doğru şekilde geri getirmez. Sonuç olarak, birçok veri erişim istemcisi ve sürücü varchar veya nvarchar veri tipini görür.

Kayıt defteri tabloları

  • Veritabanında vektör sütunu bulunan bir tablo varsa, saklanan prosedür sp_verify_database_ledger hata oluşturur.

Kullanıcı tanımlı türler

  • Vektör tipi kullanarak bir takma ad türü CREATE TYPE oluşturamazsınız. Bu kısıtlama, xml ve json veri tiplerinin davranışına benzer.

Always Encrypted (Her Zaman Şifreli)

  • Vektör türü Her Zaman Şifrelenmiş özelliğiyle desteklenmiyor.

Bilinen sorunlar

  • Veri Maskeleme şu anda vektör verilerini Azure portalında varbinary veri türü olarak gösteriyor.

İlgili içerik

  • Son güncelleştirme: