Tipo de datos vectoriales

Se aplica a: SQL Server 2025 (17.x) Base de datos SQL de AzureAzure SQL Managed InstanceBase de datos SQL en Microsoft Fabric

El tipo de dato vectorial almacena datos vectoriales optimizados para operaciones como búsqueda por similitud y aplicaciones de aprendizaje automático. Los vectores se almacenan en un formato binario optimizado, pero se exponen como matrices JSON para mayor comodidad. Cada elemento del vector se almacena como un valor de punto flotante de precisión sencilla (4 bytes).

Para proporcionar una experiencia familiar para los desarrolladores, el tipo de datos vectorial se crea y se muestra como una matriz JSON. Por ejemplo, un vector con tres dimensiones se puede representar como '[0.1, 2, 30]'. Puedes convertir implícita y explícitamente entre el tipo vectorial y los tipos varchar, nvarchar y json .

Para obtener más información sobre cómo trabajar con datos vectoriales, consulte:

• Búsqueda de vectores e índices vectoriales en el motor de base de datos sql
• Aplicaciones inteligentes

Sintaxis de ejemplo

La sintaxis de uso del tipo vector es similar a todos los demás tipos de datos de SQL Server de una tabla.

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

Por defecto, el tipo base es float32. Para usar precisión media, especifica explícitamente float16.

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

Dimensions

Un vector debe tener al menos una dimensión. El número máximo de dimensiones depende del tipo base del vector:

• Float32 soporta hasta 1.998 dimensiones.
• Float16 soporta hasta 3.996 dimensiones.

Disponibilidad de funcionalidades

El tipo de dato vectorial está disponible en todos los niveles de compatibilidad de bases de datos. Si no especificas un tipo base, el vector usa float32.

Las funcionalidades vectoriales están disponibles en Instancia Administrada de Azure SQL configurada con la directiva Always-up-to-date.

Vectores flotadores de media precisión 16

• Los vectores de media precisión (float16) están generalmente disponibles en Azure SQL Database, Azure SQL Managed Instance y SQL database en Microsoft Fabric. No se requiere ninguna configuración de vista previa.

• En SQL Server 2025 (17.x), los vectores de media precisión (float16) están disponibles en vista previa. Para usar float16 en SQL Server 2025, debes activar la PREVIEW_FEATURES opción de configuración con alcance de base de datos. Para más información, consulte Habilitar funciones de vista previa en SQL Server 2025.

Para más información sobre vectores de media precisión, véase Soporte de flotación de media precisión en el tipo de dato vectorial.

Habilitar funciones de vista previa en SQL Server 2025

Para algunas funciones de vista previa en SQL Server 2025, debes activar la PREVIEW_FEATURES opción de configuración con alcance de base de datos.

ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;
GO

Para más información, véase PREVIEW_FEATURES.

Examples

A. Definición de columna

Utiliza el tipo vector en las definiciones de columnas dentro de una instrucción CREATE TABLE. Por ejemplo:

En el ejemplo siguiente se crea una tabla con una columna vectorial y se insertan datos en ella.

Define una columna vectorial en una tabla usando el tipo base predeterminado float32 o float16 para almacenamiento a media precisió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. Uso en variables

El siguiente ejemplo declara vectores usando el nuevo tipo de dato vectorial y calcula distancias usando la VECTOR_DISTANCE función.

Utiliza el tipo vectorial con 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. Uso en procedimientos almacenados o funciones

Puedes usar el tipo de dato vectorial como parámetro en procedimientos o funciones almacenadas. Por ejemplo:

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

Conversions

• No puedes usar el tipo vectorial con el tipo sql_variant ni asignarlo a una variable o columna sql_variant . Esta restricción es similar a los tipos de datos varchar(max), varbinary(max), nvarchar(max), xml, json y CLR.

Compatibility

Mejoras en el protocolo TDS

SQL Server almacena vectores en un formato binario optimizado, pero los expone como matrices JSON para mayor comodidad.

Los controladores admitidos usan mejoras en el protocolo TDS para transmitir datos vectoriales de forma más eficaz en formato binario y presentarlos a aplicaciones como tipos de vector nativos. Este enfoque reduce el tamaño de carga, elimina la sobrecarga del análisis de JSON y conserva la precisión de punto flotante completo. Como resultado, mejora tanto el rendimiento como la precisión al trabajar con vectores de alta dimensión en escenarios de inteligencia artificial y aprendizaje automático.

Compatibilidad con controladores nativos

Las aplicaciones que usan TDS versión 7.4 o posterior y los controladores actualizados pueden leer, escribir, transmitir y copiar datos vectoriales de forma nativa.

Estas funcionalidades requieren versiones de los controladores siguientes. Asegúrese de que usa la versión correcta para habilitar la compatibilidad con vectores nativos.

• Microsoft.Data.SqlClient: la versión 6.1.0 presenta el SqlVector tipo, ampliando System.Data.SqlDbTypes.
• Microsoft JDBC Driver for SQL Server: versión Preview 13.1.0 introduce el microsoft.sql.Types.VECTOR tipo y la microsoft.sql.Vector clase.

Puede empezar a usar el nuevo tipo de vector inmediatamente. En los ejemplos siguientes se muestran diferentes idiomas y configuraciones de controladores.

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

Las siguientes herramientas admiten el tipo de datos vectorial :

• SQL Server Management Studio versión 21 y versiones posteriores
• DacFX y SqlPackage versión 162.5 (noviembre de 2024) y versiones posteriores
• La extensión de SQL Server para Visual Studio Code versión 1.32 (mayo de 2025) y versiones posteriores
• Microsoft.Build.Sql versión 1.0.0 (marzo de 2025) y versiones posteriores
• SQL Server Data Tools (Visual Studio 2022) versión 17.13 y versiones posteriores

Limitations

El tipo de vector tiene las siguientes limitaciones:

Tables

• No se soportan restricciones a nivel de columna, salvo las restricciones de NULL y NOT NULL .

  • Las restricciones DEFAULT y CHECK no se admiten para las columnas de vector.

  • Las restricciones de clave, como PRIMARY KEY o FOREIGN KEY, no se admiten para las columnas vectoriales . La igualdad, la unicidad, las combinaciones mediante columnas vectoriales como claves y los pedidos de ordenación no se aplican a los tipos de datos vectoriales .

  • No hay ninguna noción de unicidad para los vectores, por lo que las restricciones únicas no son aplicables.

  • Comprobar el rango de valores dentro de un vector no es aplicable.

• Los vectores no admiten la comparación, suma, resta, multiplicación, división, concatenación ni ningún otro operador de asignación matemático, lógico y compuesto.

• No puedes usar columnas vectoriales en tablas optimizadas para memoria.

Indexes

• No puedes usar índices B-tree ni índices columnstore en columnas vector. Sin embargo, puedes incluir una columna vectorial como columna incluida en una definición de índice.
• Los índices vectoriales crean un índice aproximado en una columna vectorial para mejorar el rendimiento de la búsqueda de vecinos más cercanos. Para saber más sobre cómo funcionan la indexación vectorial y la búsqueda vectorial, y las diferencias entre la búsqueda exacta y la aproximada, consulte Búsqueda vectorial e índices vectoriales en el SQL Motor de base de datos.

Metadatos del esquema de tabla

• El procedimiento almacenado del sistema sp_describe_first_result_set no devuelve correctamente el tipo de dato vectorial . Como resultado, muchos clientes y controladores de acceso a datos ven un tipo de dato varchar o nvarchar .

Tablas de libro de contabilidad

• El procedimiento sp_verify_database_ledger almacenado genera un error si la base de datos contiene una tabla con una columna vectorial .

Tipos definidos por el usuario

• No puedes crear un tipo de alias usando CREATE TYPE para el tipo vector . Esta restricción es similar al comportamiento de los tipos de datos xml y json .

Siempre Cifrado

• El tipo de vector no está compatible con la función Siempre Cifrado.

Problemas conocidos

• Actualmente, el enmascaramiento de datos muestra los datos vectoriales como tipo de datos varbinary en el portal de Azure.

Contenido relacionado

• Soporte para flotante de media precisión en el tipo de datos vectorial
• Búsqueda de vectores e índices vectoriales en el motor de base de datos sql
• Aplicaciones inteligentes
• Funciones de vector