矢量数据类型

适用于：SQL Server 2025 （17.x） 在Microsoft Fabric 中预览 Azure SQL 数据库Azure SQL 托管实例 SQL 数据库

矢量数据类型旨在存储针对相似性搜索和机器学习应用等操作进行了优化的矢量数据。 矢量以优化的二进制格式存储，但为了方便起见，以 JSON 数组的形式公开。 矢量的每个元素都存储为单精度（4 字节）浮点值。

为了为开发人员提供熟悉的体验，将创建 矢量 数据类型并将其显示为 JSON 数组。 例如，具有三个维度的向量可以表示为 '[0.1, 2, 30]'。 可以使用 varchar、nvarchar 和 json 类型实现从vector类型和到vector类型的隐式和显式转换。

注意

有关限制，请查看 “限制 ”和 “已知”问题。

矢量功能在配置了 Always-up-to-date 策略的 Azure SQL 托管实例中可用。

若要详细了解如何使用矢量数据，请参阅：

• SQL 数据库引擎中的矢量概述
• 智能应用程序

示例语法

矢量类型的使用语法与表中的所有其他 SQL Server 数据类型类似。

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

维度

矢量必须至少有一个维度。 支持的最大维度数为 1998。

示例

答： 列定义

矢量类型可用于 CREATE TABLE 语句中包含的列定义，例如：

以下示例创建一个包含矢量列的表并将数据插入其中。

CREATE TABLE dbo.vectors
(
  id INT PRIMARY KEY,
  v VECTOR(3) NOT NULL
);

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. 在变量中的用法

以下示例使用新的矢量数据类型来声明矢量，并使用 VECTOR_DISTANCE 函数来计算距离。

矢量类型可与变量配合使用：

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

°C 在存储过程或函数中的用法

矢量数据类型可用作存储过程或函数中的参数。 例如：

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

功能可用性

新的矢量类型在所有数据库兼容性级别下可用。

转换

• 矢量类型不能与 sql_variant 类型配合使用，也不能分配给 sql_variant 变量或列。 此限制类似于 varchar（max）、 varbinary（max）、 nvarchar（max）、 xml、 json 和基于 CLR 的数据类型。

兼容性

TDS 协议的增强功能

SQL Server 以优化的二进制格式存储矢量，但为了方便起见，将它们公开为 JSON 数组。 支持的 驱动程序使用 TDS 协议的增强功能以二进制格式更有效地传输矢量数据，并将其作为本机向量类型呈现给应用程序。 此方法可减少有效负载大小，消除 JSON 分析的开销，并保留完整的浮点精度。 因此，在 AI 和机器学习方案中处理高维矢量时，它提高了性能和准确性。

本机驱动程序支持

使用 TDS 版本 7.4 或更高版本 和更新的驱动程序的应用程序可以本机读取、写入、流式传输和大容量复制向量数据。

这些功能需要下面列出的驱动程序的版本。 确保使用正确的版本来启用本机向量支持。

• Microsoft.Data.SqlClient：版本 6.1.0 引入了类型 SqlVector ，扩展 System.Data.SqlDbTypes。
• Microsoft JDBC Driver for SQL Server：版本 13.1.0 预览版 引入了 microsoft.sql.Types.VECTOR 类型和 microsoft.sql.Vector 类。

注意

对于不支持更新的 TDS 协议的客户端，SQL Server 将继续将矢量数据公开为 varchar（max） 类型，以确保向后兼容。 客户端应用程序可以使用矢量数据，就像它是 JSON 数组一样。 SQL 数据库引擎自动将矢量转换为 JSON 数组并从 JSON 数组转换回来，这使得新类型对客户端而言是透明的。 因此，驱动程序和所有语言都自动与新类型兼容。

可以立即开始使用新的 向量 类型。 以下示例显示了不同的语言和驱动程序配置。

。网

重要

需要 Microsoft.Data.SqlClient 6.1.0 或更高版本来支持本机向量。

static void InsertNonNullVal(SqlConnection conn)
{
    Console.WriteLine("Inserting non-null value with SqlDbType");

    using SqlCommand command = new SqlCommand("INSERT INTO dbo.vectors VALUES (@Id, @VectorData)", conn);

    command.Parameters.AddWithValue("@Id", 1);

    var vectorParameter = new SqlParameter("@VectorData", Microsoft.Data.SqlDbTypeExtensions.Vector);
    vectorParameter.Value = new Microsoft.Data.SqlTypes.SqlVectorFloat32(new float[] { 3.14159f, 1.61803f, 1.41421f });
    command.Parameters.Add(vectorParameter);

    command.ExecuteNonQuery();
}

static void ReadWithGetValue(SqlConnection connection)
{
    Console.WriteLine("Reading values using GetValue method:");

    using (SqlCommand commandSourceData = new SqlCommand("SELECT v FROM dbo.vectors;", connection))
    using (SqlDataReader reader = commandSourceData.ExecuteReader())
    while (reader.Read())
    {
        var vector = reader.GetValue(0);        
        if (vector != null && vector != DBNull.Value)
        {
            Console.WriteLine("Type: " + vector.GetType() + " Element Count: " + ((SqlVectorFloat32)vector).Length);

            var values = ((SqlVectorFloat32)vector).Values;
            Console.WriteLine("Values: " + string.Join(", ", values));
        }              
    }
}

注意

如果不使用最新的 .NET 驱动程序，仍可以通过使用类将矢量数据序列化和反序列化为 JSON 字符串来处理 JsonSerializer 中的矢量数据。 这可确保与 SQL Server 为旧客户端公开的矢量的 varchar(max) 表示形式兼容。

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

重要

需要Microsoft JDBC Driver for SQL Server 13.1.0 预览版或更高版本以支持本机矢量类型。

将向量数据插入表中的示例

@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，应用程序可以使用 Python 编写和读取矢量数据json.loadsjson.dumps：此示例将 Python 与适用于 SQL Server 的最新Microsoft官方 Python 驱动程序配合使用。 应用程序可以使用 json.loads 和 json.dumps 写入和读取矢量数据。

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）

此示例使用 Python 和社区开发的常用 PyODBC 驱动程序。 应用程序可以使用 json.loads 和 json.dumps 写入和读取矢量数据。

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 函数的详细信息，请参阅迁移 Python 应用程序以将无密码连接用于 Azure SQL 数据库。

警告

请确保在用于 Python 的连接字符串中添加 LongAsMax=yes，以使用 nvarchar（max） 类型发送数据，而不是过时的 ntext，以避免任何转换错误消息， 例如：“DataError： （'22018'， '[22018] [Microsoft][ODBC Driver 17 for SQL Server][SQL Server]Operand 类型冲突： ntext 与向量 （206） （SQLExecDirectW）' 不兼容”。 有关详细信息，请参阅 PyODBC - LongAsMax。

工具

以下工具支持 向量 数据类型：

• SQL Server Management Studio 版本 21 及更高版本
• DacFX 和 SqlPackage 版本 162.5（2024 年 11 月）及更高版本
• 适用于 Visual Studio Code 的 SQL Server 扩展 版本 1.32（2025 年 5 月）及更高版本
• Microsoft.Build.Sql 版本 1.0.0（2025 年 3 月）及更高版本
• SQL Server Data Tools （Visual Studio 2022） 版本 17.13 及更高版本

限制

矢量类型具有以下限制：

表

• 列级约束不支持，NULL/NOT NULL 约束除外。
  • DEFAULT和CHECK的约束不被支持在矢量列。
  • 矢量列不支持关键约束，例如PRIMARY KEY或FOREIGN KEY。 相等性、唯一性、使用向量列作为键联接，排序顺序不适用于 矢量 数据类型。
  • 矢量没有唯一性的概念，因此唯一约束不适用。
  • 在矢量内检查值的范围的操作也不适用。
• 矢量不支持比较、加法、减法、乘法、除法、串联或任何其他数学、逻辑和复合赋值运算符。
• 矢量 列不能在内存优化表中使用。

索引

• 矢量列上不允许使用 B 树索引或列存储索引。 不过，可以将矢量列指定为索引定义中包含的列。

表架构元数据

• sp_describe_first_result_set 系统存储过程不会正确返回矢量数据类型。 因此，许多数据访问客户端和驱动程序都会看到 varchar 或 nvarchar 数据类型。

账本表

• 如果数据库包含具有sp_verify_database_ledger列的表，存储过程将生成错误。

用户定义类型

• 不允许使用 CREATE TYPE 为矢量类型创建别名类型，这与 xml 和 json 数据类型的行为类似。

始终加密 (Always Encrypted)

• Always Encrypted 功能不支持向量类型。

已知问题

• 数据掩码当前在 Azure 门户中以 varbinary 数据类型的形式显示矢量数据。

相关内容

• SQL 数据库引擎中的矢量概述
• 智能应用程序
• 矢量函数