Type de données vectorielles

S’applique à : SQL Server 2025 (17.x) Azure SQL DatabaseAzure SQL Managed InstanceBase de données SQL dans Microsoft Fabric

Le type de données vectorielles stocke des données vectorielles optimisées pour des opérations telles que la recherche par similarité et les applications d’apprentissage automatique. Les vecteurs sont stockés dans un format binaire optimisé, mais sont exposés sous forme de tableaux JSON pour des raisons pratiques. Chaque élément du vecteur est stocké sous forme de valeur à virgule flottante (4 octets) simple précision.

Pour offrir une expérience familière aux développeurs, le type de données vectorielles est créé et affiché sous la forme d’un tableau JSON. Par exemple, un vecteur avec trois dimensions peut être représenté en tant que '[0.1, 2, 30]'. Vous pouvez implicitement et explicitement convertir entre le type vectoriel et les types varchar, nvarchar et json .

Pour plus d’informations sur l’utilisation des données Vecteur, consultez :

• Recherche vectorielle et index vectoriels dans le moteur de base de données SQL
• Applications intelligentes

Exemple de syntaxe

La syntaxe d’utilisation du type vecteur est similaire à tous les autres types de données SQL Server dans une table.

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

Par défaut, le type de base est float32. Pour utiliser la demi-précision, spécifiez explicitement float16 .

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

Dimensions

Un vecteur doit avoir au moins une dimension. Le nombre maximal de dimensions dépend du type de base vectoriel :

• Float32 supporte jusqu’à 1 998 dimensions.
• Float16 supporte jusqu’à 3 996 dimensions.

Disponibilité des fonctionnalités

Le type de données vectoriel est disponible à tous les niveaux de compatibilité des bases de données. Si vous ne spécifiez pas de type de base, le vecteur utilise float32.

Les fonctionnalités vectorielles sont disponibles dans Azure SQL Managed Instance configurée avec la stratégie Always-up-to-date .

Vecteurs float16 à demi-précision

• Les vecteurs demi-précision (float16) sont généralement disponibles dans Azure SQL Database, Azure SQL Managed Instance et SQL Database dans Microsoft Fabric. Aucune configuration de prévisualisation n’est requise.

• Dans SQL Server 2025 (17.x), des vecteurs à demi-précision (float16) sont disponibles en aperçu. Pour utiliser float16 dans SQL Server 2025, vous devez activer l’option PREVIEW_FEATURES de configuration avec portée de base de données. Pour plus d’informations, voir Activer les fonctionnalités d’aperçu dans SQL Server 2025.

Pour plus d’informations sur les vecteurs demi-précision, voir Soutien du flotteur demi-précision dans le type de données vectorielle.

Activer les fonctionnalités de prévisualisation dans SQL Server 2025

Pour certaines fonctionnalités d’aperçu dans SQL Server 2025, vous devez activer l’option PREVIEW_FEATURES de configuration à portée de base de données.

ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;
GO

Pour plus d’informations, voir PREVIEW_FEATURES.

Examples

A. Définition de colonne

Utilisez le type de vecteur dans les définitions de colonnes au sein d’une CREATE TABLE instruction. Par exemple:

L’exemple suivant crée une table avec une colonne vectorielle et y insère des données.

Définissez une colonne vectorielle dans un tableau en utilisant soit le type de base par défaut float32 , soit float16 pour un stockage à demi-précision.

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. Utilisation dans les variables

L’exemple suivant déclare des vecteurs en utilisant le nouveau type de données vectorielles et calcule les distances en utilisant la VECTOR_DISTANCE fonction.

Utilisez le type de vecteur avec variables :

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. Utilisation dans les procédures stockées ou fonctions

Vous pouvez utiliser le type de données vectoriel comme paramètre dans des procédures ou fonctions stockées. Par exemple:

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

Conversions

• Vous ne pouvez pas utiliser le type vectoriel avec le type sql_variant ni l’assigner à une variable ou une colonne sql_variant . Cette restriction est similaire à varchar(max),varbinary(max), nvarchar(max), xml, json et aux types de données basés sur CLR.

Compatibility

Améliorations apportées au protocole TDS

SQL Server stocke les vecteurs dans un format binaire optimisé, mais les expose sous forme de tableaux JSON pour des raisons pratiques.

Les pilotes pris en charge utilisent des améliorations apportées au protocole TDS pour transmettre des données vectorielles plus efficacement au format binaire et les présenter aux applications en tant que types vectoriels natifs. Cette approche réduit la taille de la charge utile, élimine la surcharge de l’analyse JSON et conserve la précision à virgule flottante complète. Par conséquent, il améliore les performances et la précision lors de l’utilisation de vecteurs haute dimensionnels dans les scénarios IA et Machine Learning.

Prise en charge native des pilotes.

Les applications utilisant TDS version 7.4 ou ultérieure et les pilotes mis à jour peuvent lire, écrire, diffuser et copier en bloc des données vectorielles en mode natif.

Ces fonctionnalités nécessitent des versions des pilotes suivants. Vérifiez que vous utilisez la version correcte pour activer la prise en charge des vecteurs natifs.

• Microsoft.Data.SqlClient : la version 6.1.0 introduit le SqlVector type, extension System.Data.SqlDbTypes.
• Microsoft JDBC Driver pour SQL Server : la version 13.1.0 Preview introduit le microsoft.sql.Types.VECTOR type et la microsoft.sql.Vector classe.

Vous pouvez commencer à utiliser immédiatement le nouveau type de vecteur . Les exemples suivants montrent différentes langues et configurations de pilotes.

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

Les outils suivants prennent en charge le type de données vectorielles :

• SQL Server Management Studio version 21 et versions ultérieures
• DacFX et SqlPackage version 162.5 (novembre 2024) et versions ultérieures
• Extension SQL Server pour Visual Studio Code version 1.32 (mai 2025) et versions ultérieures
• Microsoft.Build.Sql version 1.0.0 (mars 2025) et versions ultérieures
• SQL Server Data Tools (Visual Studio 2022) version 17.13 et versions ultérieures

Limitations

Le type de vecteur présente les limitations suivantes :

Tables

• Les contraintes au niveau des colonnes ne sont pas prises en charge, à l’exception des contraintes NULL et NOT NULL.

  • DEFAULT et CHECK contraintes ne sont pas prises en charge pour les colonnes vecteur.

  • Les contraintes clés, telles que PRIMARY KEY ou FOREIGN KEY, ne sont pas prises en charge pour les colonnes vectorielles . L’égalité, l’unicité, les jointures à l’aide de colonnes vectorielles en tant que clés et les ordres de tri ne s’appliquent pas aux types de données vectorielles .

  • Il n’existe aucune notion d’unicité pour les vecteurs. Par conséquent, les contraintes uniques ne s’appliquent pas.

  • Vérifier la plage de valeurs dans un vecteur n’est pas applicable.

• Les vecteurs ne prennent pas en charge la comparaison, l’addition, la soustraction, la multiplication, la division, la concaténation ou tout autre opérateur d’affectation mathématique, logique et composée.

• Vous ne pouvez pas utiliser de colonnes vectorielles dans des tables optimisées en mémoire.

Indexes

• Vous ne pouvez pas utiliser d’index B-tree ou d’index columnstore sur des colonnes vector. Cependant, vous pouvez inclure une colonne vectorielle comme colonne incluse dans une définition d’index.
• Les index vectoriels créent un indice approximatif sur une colonne vectorielle afin d’améliorer les performances de la recherche des plus proches voisins. Pour en savoir plus sur le fonctionnement de l’indexation vectorielle et de la recherche vectorielle, ainsi que sur les différences entre la recherche exacte et la recherche approximative, voir Recherche vectorielle et indexes vectoriels dans le SQL Moteur de base de données.

Métadonnées de schéma de table

• La procédure stockée du système sp_describe_first_result_set ne retourne pas correctement le type de données vectoriel . En conséquence, de nombreux clients d’accès aux données et pilotes voient un type de données varchar ou nvarchar .

Tables de registre

• La procédure sp_verify_database_ledger stockée génère une erreur si la base de données contient une table avec une colonne vectoriel .

Types définis par l'utilisateur

• On ne peut pas créer un type d’alias en utilisant CREATE TYPE pour le type vectoriel . Cette restriction est similaire au comportement des types de données xml et json .

Toujours Chiffré

• Le type de vecteur n’est pas pris en charge par la fonction Toujours Crypté.

Problèmes connus

• Le masquage de données affiche actuellement des données vectorielles en tant que type de données varbinary dans le portail Azure.

Contenu connexe

• Prise en charge du flottant à demi-précision dans le type de données vectoriel
• Recherche vectorielle et index vectoriels dans le moteur de base de données SQL
• Applications intelligentes
• Fonctions vecteur