Partager via

Type de données vectorielles

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

Le type de données vecteur est conçu pour stocker les données vectorielles optimisées pour les opérations telles que la recherche de similarité et les applications Machine Learning. 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]'. La conversion implicite et explicite depuis et vers le type de vecteur peut être effectuée à l’aide de types varchar, nvarchar et json .

Note

SQL Server 2025 (17.x) prend en charge les vecteurs de demi-précision (float16). Pour plus d’informations, consultez la prise en charge à demi-précision flottante du type de données vectorielles.

float16 vector est actuellement disponible en aperçu. Pour tester, activez l’option de configuration au niveau de la PREVIEW_FEATURES base de données. Pour plus d’informations, consultez PREVIEW_FEATURES = { ON | OFF }.

ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;
GO

Pour connaître les limitations, passez en revue les limitations et les problèmes connus.

Note

Les fonctionnalités vectorielles sont disponibles dans Azure SQL Managed Instance configurée avec la stratégie [Always-up-to-date](/azure/azure-sql/managed-instance/ update-policy#always-up-to-date-update-policy).

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

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, vous devez spécifier float16 explicitement.

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

Dimensions

Un vecteur doit avoir au moins une dimension. Le nombre maximal de dimensions prises en charge est 1998.

Examples

A. Définition de colonne

Le type de vecteur peut être utilisé dans la définition de colonne contenue dans une instruction CREATE TABLE, par exemple :

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

Vous pouvez définir une colonne vectorielle dans une table à l’aide du type de base par défaut (float32) ou spécifier float16 explicitement pour le 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
(
    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 à l’aide du nouveau type de données vecteur et calcule les distances à l’aide de la fonction VECTOR_DISTANCE.

Le type de vecteur peut être utilisé avec des variables :

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

C. Utilisation dans les procédures stockées ou fonctions

Le type de données vecteur peut être utilisé comme paramètre dans la procédure stockée ou les fonctions. Par exemple:

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

Disponibilité des fonctionnalités

Le nouveau type vecteur est disponible sous tous les niveaux de compatibilité de base de données.

La prise en charge des float16 vecteurs est actuellement limitée par la configuration PREVIEW_FEATURES. Vous devez l’activer explicitement avant d’utiliser VECTOR(..., float16).

ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;
GO

Conversions

  • Le type vecteur ne peut pas être utilisé avec le type sql_variant ou affecté à 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.

Note

float16 Les vecteurs sont actuellement transmis sous forme de varchar(max ) (tableau JSON) sur TDS. La prise en charge du transport binaire pour float16 n'est pas encore prise en charge par des pilotes tels qu'ODBC, JDBC et .NET.

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.

Note

Pour les clients qui ne prennent pas en charge le protocole TDS mis à jour, SQL Server continue d’exposer des données vectorielles en tant que types varchar(max) pour garantir la compatibilité descendante. Les applications clientes peuvent utiliser des données vectorielles comme s’il s’agissait d’un tableau JSON. Le moteur de base de données SQL convertit automatiquement les vecteurs vers et à partir d’un tableau JSON, ce qui rend le nouveau type transparent pour le client. Par conséquent, les pilotes et toutes les langues sont automatiquement compatibles avec le nouveau type.

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

Important

Nécessite Microsoft.Data.SqlClient 6.1.0 ou version ultérieure pour la prise en charge native des vecteurs.

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

Si vous n’utilisez pas les derniers pilotes .NET, vous pouvez toujours utiliser des données vectorielles en C# en sérialisant et désérialisant celle-ci en tant que chaîne JSON à l’aide de la JsonSerializer classe. Cela garantit la compatibilité avec la varchar(max) représentation des vecteurs exposés par SQL Server pour les clients plus anciens.

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

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

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 NULL/NOT NULL contraintes.

    • 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.

    • La vérification de 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.

  • Les colonnes vectorielles ne peuvent pas être utilisées dans les tables optimisées en mémoire.

Indexes

  • Les index B-tree ou columnstore ne sont pas autorisés sur les colonnes vectorielles . Toutefois, une colonne vecteur peut être spécifiée en tant que colonne incluse dans une définition d’index.

Métadonnées de schéma de table

  • La procédure stockée système sp_describe_first_result_set ne retourne pas correctement le type de données vecteur. Par conséquent, de nombreux clients et pilotes d’accès aux données 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 vectorielle .

Types définis par l'utilisateur

  • La création d’un type d’alias à l’aide de CREATE TYPE pour le type de vecteur n’est pas autorisée, comme le comportement des types de données xml et json.

Toujours Chiffré

  • Le type de vecteur n’est pas pris en charge avec la fonctionnalité Always Encrypted.

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

  • Last updated on