Vektör veri türü

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

vektör veri türü, benzerlik arama ve makine öğrenmesi uygulamaları gibi işlemler için iyileştirilmiş vektör verilerini depolamak için tasarlanmıştır. 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 türüne ve vektör türünden örtük ve açık dönüştürmeler varchar, nvarchar ve json türleri kullanılarak yapılabilir.

Note

SQL Server 2025 (17.x), yarı duyarlık (float16) vektörlerini destekler. Daha fazla bilgi için bkz. Vektör veri tipinde yarı hassasiyetli kayan nokta desteği.

float16 vektör şu anda önizleme için kullanılabilir. Test etmek için veritabanı kapsamlı yapılandırma seçeneğini etkinleştirin PREVIEW_FEATURES . Ayrıntılar için PREVIEW_FEATURES = { AÇIK | KAPALI } kısmını gözden geçirin.

ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;
GO

Sınırlamalar için Sınırlamalar ve Bilinen sorunlar'ı gözden geçirin.

Note

Azure SQL Yönetilen Örneği'nde [Always-up-to-date](/azure/azure-sql/managed-instance/update-policy#always-up-to-date-update-policy) ilkesiyle yapılandırılmış vektör özellikleri mevcuttur.

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

• SQL Veritabanı Altyapısı'nda vektör arama ve vektör dizinleri
• Akıllı uygulamalar

Ö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 tür şeklindedir float32. Yarı duyarlık kullanmak için açıkça belirtmeniz float16 gerekir.

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

Dimensions

Vektör en az bir boyuta sahip olmalıdır. Desteklenen boyut sayısı üst sınırı 1998'dir.

Examples

A. Sütun tanımı

vektör türü, CREATE TABLE deyiminde yer alan sütun tanımında kullanılabilir, örneğin:

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

Varsayılan temel türü () kullanarak bir tabloda float32 sütunu tanımlayabilir veya yarı duyarlıklı depolama için açıkça belirtebilirsinizfloat16.

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

Aşağıdaki örnek, yeni vektör veri türünü kullanarak vektörleri bildirir ve VECTOR_DISTANCE işlevini kullanarak mesafeleri hesaplar.

vektör türü değişkenlerle kullanılabilir:

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

C. Saklı yordamlarda veya işlevlerde kullanım

vektör veri türü saklı yordam veya işlevlerde parametre olarak kullanılabilir. Örneğin:

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

Özellik kullanılabilirliği

Yeni vektör türü tüm veritabanı uyumluluk düzeylerinde kullanılabilir.

float16 vektör desteği şu anda PREVIEW_FEATURES yapılandırması tarafından sınırlandırılmıştır. VECTOR(..., float16) kullanmadan önce açık bir şekilde etkinleştirmeniz gerekir.

ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;
GO

Conversions

• vektör türü, sql_variant türüyle kullanılamaz veya sql_variant bir değişkene veya sütuna atanamaz. 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.

Note

float16 vektörleri şu anda TDS üzerinden varchar(max) (JSON dizisi) olarak iletilir. için float16 ikili aktarım desteği henüz ODBC, JDBC ve .NET gibi sürücülerde sağlanmamıştı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

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.

.NET

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 verilerini JSON dizesi olarak serileştirerek ve tersine serileştirerek çalışmaya devam edebilirsiniz. SQL Server tarafından eski istemciler için kullanıma sunulan vektörlerin varchar(max) gösterimi ile 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));
    }
}

JDBC

Şunlar için geçerlidir: SQL Server 13.1.0 ve sonraki sürümleri için Microsoft JDBC Sürücüsü.

Tabloya vektör verilerini ekleme örneği:

@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("---");
            }
        }
    }
}

Tablodan vektör verilerini seçme örneği:

@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("---");
                }
            }
        }
    }

Python (mssql-python)

Python ile uygulamalar json.loads kullanarak vektör verilerini yazabilir ve json.dumps okuyabilir.

Bu örnek, SQL Server için en son Microsoft resmi Python sürücüsüyle Python'u kullanıyor. Uygulamalar json.loads ve json.dumps kullanarak vektör verilerini yazabilir ve okuyabilir.

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()

Python (PyODBC)

Bu örnek, topluluk tarafından kullanılan popüler PyODBC sürücüsüyle Python kullanıyor. Uygulamalar json.loads ve json.dumps kullanarak vektör verilerini yazabilir ve okuyabilir.

import os, json
from utilities import get_conn

conn = get_conn()
conn = get_conn(os.environ["MSSQL"])

cursor = conn.cursor()
query = "INSERT INTO dbo.vectors VALUES(100, ?)"
cursor.execute(query, json.dumps([1,2,3]))
cursor.commit()
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()

get_conn işlevi hakkında daha fazla bilgi için bkz. Azure SQL Veritabanıile parolasız bağlantıları kullanmak için Python uygulamasını geçirme.

Eski LongAsMax=yes yerine nvarchar(max) türünü kullanarak veri göndermek için Python ile kullanılan bağlantı dizesini eklediğinizden emin olun. Bu seçenek, aşağıdakiler gibi dönüştürme hata iletilerini önler:

DataError: ('22018', '[22018] [Microsoft][ODBC Driver 17 for SQL Server][SQL Server]Operand type clash: ntext is incompatible with vector (206) (SQLExecDirectW)').

Daha fazla bilgi için bkz. PyODBC - LongAsMax.

Tools

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

• SQL Server Management Studio sürüm 21 ve sonraki sürümleri
• DacFX ve SqlPackage sürüm 162.5 (Kasım 2024) ve sonraki sürümleri
• Visual Studio Code için SQL Server uzantısının 1.32 (Mayıs 2025) ve sonraki sürümleri
• Microsoft.Build.Sql sürüm 1.0.0 (Mart 2025) ve sonraki sürümleri
• SQL Server Veri Araçları (Visual Studio 2022) sürüm 17.13 ve sonraki sürümleri

Limitations

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

Tables

• Kısıtlamalar dışında NULL/NOT NULL sütun düzeyinde kısıtlamalar desteklenmez.

  • 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ın denetlenmesi de 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ı bellek için iyileştirilmiş tablolarda kullanılamaz.

Indexes

• Vektör sütunlarında B ağacı dizinlerine veya columnstore dizinlerine izin verilmez. Ancak, bir vektör sütunu, dizin tanımına eklenmiş bir sütun olarak belirtilebilir.

Tablo şeması meta verileri

• sp_describe_first_result_set sistem saklı yordamı, vektör veri türünü doğru şekilde döndürmez. Bu nedenle, birçok veri erişim istemcisi ve sürücüsü varchar veya nvarchar veri türünü görür.

Kayıt defteri tabloları

• Veritabanında sp_verify_database_ledger sütunu olan bir tablo varsa saklı yordam bir hata oluşturur.

Kullanıcı tanımlı türler

• CREATE TYPE ve json veri türlerinin davranışına benzer şekilde, vektör türü için kullanılarak diğer ad türü oluşturulmasına izin verilmez.

Always Encrypted (Her Zaman Şifreli)

• vektör türü Always Encrypted özelliğiyle desteklenmez.

Bilinen sorunlar

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

İlgili içerik

• Vektör veri türünde yarım hassasiyetli float desteği
• SQL Veritabanı Altyapısı'nda vektör arama ve vektör dizinleri
• Akıllı uygulamalar
• Vector işlevleri