CREATE VECTOR INDEX （Transact-SQL）

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

在向量列上创建一个近似索引，以提升最近邻搜索的性能。 想了解更多向量索引和向量搜索的工作原理，以及精确搜索和近似搜索的区别，请参见SQL 数据库引擎中的向量搜索和向量索引。

功能可用性

  • 向量索引和VECTOR_SEARCH在Azure SQL 数据库中普遍可用（GA），SQL数据库在Microsoft Fabric，并且Azure SQL 托管实例始终 up-to日期更新策略。
  • 向量索引和VECTOR_SEARCH是SQL Server 2025（17.x）以及SQL Server 2025更新策略中Azure SQL 托管实例中的预览功能。

警告

弃用通知：当前版本支持使用早期数据结构创建的向量索引，但未来版本将会被淘汰。 为确保未来兼容性及最新矢量搜索功能，请使用“ 迁移自早期矢量索引 版本”部分的步骤迁移现有矢量索引。

SQL Server 2025 预览功能

在 SQL Server 2025 和 SQL Server 2025更新策略中的 Azure SQL 托管实例 中，矢量索引和VECTOR_SEARCH函数处于预览阶段，可能会有变更。 要使用此功能，您必须启用 PREVIEW_FEATURES数据库范围配置。

使用前请检查 当前的限制 。

注释

向量索引的最新版本支持Azure SQL 数据库，SQL 数据库支持，Microsoft Fabric 版本，Azure SQL 托管实例 支持始终up-to日期更新策略。

语法

Transact-SQL 语法约定

CREATE VECTOR INDEX index_name
ON object ( vector_column )
[ WITH (
    [ , ] METRIC = { 'cosine' | 'dot' | 'euclidean' }
    [ [ , ] TYPE = 'DiskANN' ]
    [ [ , ] MAXDOP = max_degree_of_parallelism ]
) ]
[ ON { filegroup_name | "default" } ]
[;]

论据

index_name

索引的名称。 索引名称在表中必须唯一，但不必在数据库中是唯一的。 索引名称必须遵循 标识符规则。

对象

在其中创建索引的表。 它必须是基表。 不支持视图、临时表（本地表和全局表）。

vector_column

用于创建向量索引的列。 它必须是 矢量 类型。

度量

一个字符串，其中包含用于计算两个给定向量之间的距离的距离指标的名称。 支持以下距离指标：

  • cosine - 余弦距离
  • euclidean - Euclidean 距离
  • dot - （负数） 点积

TYPE

用于生成索引的 ANN 算法 的类型。 目前仅支持 DiskANN。 DiskANN 是默认值。

MAXDOP

替代索引作的 最大并行度 配置选项。 有关详细信息，请参阅 服务器配置：最大并行度。 使用 MAXDOP 来限制索引生成作的并行度和生成的资源消耗。

max_degree_of_parallelism 可以是：

  • 1

    取消生成并行计划。

  • >1

    根据当前系统工作负荷，将并行索引作中使用的最大并行度限制为指定数目或更少。

  • 0（默认值）

    使用在服务器、数据库或工作负荷组级别指定的并行度，除非根据当前系统工作负荷减少。

    有关详细信息，请参阅 配置并行索引作。

    并行索引操作并不适用于 SQL Server 的所有版本。 有关SQL Server各版本支持的功能列表，请参见SQL Server 2025的版本及支持功能。

将矢量索引升级到最新版本

重要

弃用通知：当前版本支持使用早期数据结构创建的向量索引，但未来版本将取消该支持。 为确保未来兼容性及最新向量搜索功能，请通过以下步骤迁移现有向量索引。

新创建的向量索引自动使用最新的数据结构，该结构提供：

  • 完全 DML 支持：删除在创建索引后使矢量索引表只读的先前限制。 你现在可以在自动、实时索引维护的同时，执行 INSERT、 UPDATE、 DELETE和 MERGE 操作，同时保持向量索引功能。
  • 迭代过滤：在向量搜索过程中应用从句中的谓词 WHERE ，而非检索后。
  • 优化器驱动：查询优化器根据查询特性自动决定是使用 DiskANN 索引还是 kNN 搜索。
  • 高级量化：集成向量量化技术，提供更好的存储效率和更快的查询性能。 这些优化对用户来说是透明的。

有关 早期向量索引版本限制的详细信息，请参见“局限性与注意事项”部分。

从早期矢量索引版本迁移

要启用最新功能，你必须丢弃并重建使用早期版本的向量索引。 本部分介绍如何识别、迁移和验证向量索引版本。

步骤 1：标识现有矢量索引

使用以下查询标识需要迁移的矢量索引：

SELECT
    i.name AS index_name,
    t.name AS table_name,
    JSON_VALUE(v.build_parameters, '$.Version') AS index_version,
    CASE
        WHEN JSON_VALUE(v.build_parameters, '$.Version') >= '3'
            THEN 'Uses latest version (no migration required)'
        WHEN JSON_VALUE(v.build_parameters, '$.Version') < '3'
            THEN 'Created using an earlier version (migration recommended)'
        ELSE 'Unknown format'
    END AS migration_status
FROM sys.vector_indexes AS v
    INNER JOIN sys.indexes AS i
        ON v.object_id = i.object_id
        AND v.index_id = i.index_id
    INNER JOIN sys.tables AS t
        ON v.object_id = t.object_id
ORDER BY t.name, i.name;
如何解释结果

使用最新版本

  • 已支持迭代滤波、完整的DML支持、优化器驱动的执行以及改进的量化。
  • 无需迁移。

使用早期版本创建

  • 使用遗留的后滤波行为。
  • 不支持最新的矢量搜索功能。
  • 强烈建议迁移以确保未来的兼容性。

步骤 2：删除并重新创建向量索引

你无法升级使用早期格式的向量索引。 若要启用最新的 DiskANN 功能，请删除并重新创建索引。

警告

服务影响：删除向量索引会立即禁用受影响表的近似矢量搜索，直到重新创建索引。 在生产系统的维护时段内规划迁移。

删除现有索引
DROP INDEX vec_idx ON dbo.wikipedia_articles;
重新创建索引
CREATE VECTOR INDEX vec_idx
    ON dbo.wikipedia_articles (title_vector)
    WITH (
        TYPE = 'DISKANN',
        METRIC = 'COSINE'
    );

注释

使用当前 CREATE VECTOR INDEX 语句创建的向量索引会自动使用最新的 DiskANN 格式。 无需其他选项或标志。

步骤 3：验证索引版本

重新创建索引后，确认它使用的是最新版本：

SELECT
    i.name AS index_name,
    t.name AS table_name,
    JSON_VALUE(v.build_parameters, '$.Version') AS index_version
FROM sys.vector_indexes AS v
    INNER JOIN sys.indexes AS i
        ON v.object_id = i.object_id
        AND v.index_id = i.index_id
    INNER JOIN sys.tables AS t
        ON v.object_id = t.object_id
WHERE i.name = 'vec_idx';

该 index_version 列应 3 显示最新版本。

版本不兼容的错误行为

如果尝试将 TOP_N 参数 VECTOR_SEARCH 与最新版本矢量索引一起使用，SQL Server 将返回以下错误：

Msg 42274, Level 16, State 1
Vector search with version 3 index does not support explicit TOP_N parameter.

若要解决此错误，请从TOP_N中删除VECTOR_SEARCH参数并使用SELECT TOP (N) WITH APPROXIMATE语法。 有关详细信息，请参阅 使用旧语法时出错。

限制和注意事项

早期矢量索引版本限制

早期的向量索引版本存在以下限制。 若要检查索引版本，请参阅 “验证索引版本”。

  • 仅限后过滤：谓词仅在向量检索后应用，不在搜索过程中。 这种行为可能导致应用筛选时返回的行数低于预期。

  • 只读表：具有矢量索引的表是只读的。 创建向量索引后，你无法执行DML操作（INSERT， UPDATE， DELETEMERGE， ）。 ALLOW_STALE_VECTOR_INDEX如果可以容忍过时的搜索结果，请使用数据库范围的配置启用 DML 操作。

  • 手动TOP_N调：你必须手动调整 TOP_N 参数 VECTOR_SEARCH 以补偿后滤波。 你通常需要超大数值才能获得理想的结果数量。

当前限制（也适用于最新版本）

当前预览版具有以下限制：

  • 你不能对向量索引进行分区。

  • 该表必须在 整数 列上有主键聚类索引。

  • 矢量索引不会复制到订阅服务器。

  • 你不能用 TRUNCATE TABLE来截断带有向量索引的表格。 若要删除所有数据，请先删除向量索引，截断表，重新填充至少 100 行，然后重新创建索引。 更多信息请参见 TRUNCATE TABLE 限制。

  • 向量索引无法在 DacPac 中部署。 你可以从 DacFx 170.5.96 版本开始部署包含向量索引的数据库。 向量索引是在表数据加载后创建的，索引表必须包含至少100行非NULL 向量值。

    在仅模式的DACPAC部署中，如果目标表中非NULL 向量值的行少于100行，部署可以在不创建向量索引的情况下成功。 DacFx 在后续添加行时不会自动创建跳过的索引。 加载至少100行合格行后，使用部署后脚本创建向量索引，重新发布DACPAC，或运行 CREATE VECTOR INDEX。

    导入或部署后，通过查询 sys.vector_indexes验证向量索引是否已创建。

    作为变通方法，在DacFx 170.5.96版本之前，导出数据库前先删除向量索引，导入后重新创建索引。

最低数据要求

向量索引需要至少有数行NULL 非向量值，才能创建索引。

  • 最小行数：表格中必须至少有100行非NULL 向量值。
  • 错误行为：如果你尝试在少于100行的表上创建向量索引，操作失败并返回错误Msg 42266。

示例错误：

Msg 42266, Level 16, State 1
Cannot create a vector index. The table contains only 8 rows with non-null vectors, 
but at least 100 are required for vector index creation.

最佳做法：在创建向量索引之前，使用至少 100 行填充表。 对于需要更少行数的开发和测试场景， VECTOR_SEARCH 可以使用暴力破解扫描方法，无需索引即可实现。 然而，这种方法在数据集越大时会降低性能。

DML 支持

当你使用最新版本创建 DiskANN 向量索引时，该表不再是只读的。 您可以通过标准数据操作语言（DML）操作修改数据，这些更改会自动出现在向量搜索结果中。

此功能使矢量搜索适用于数据随时间变化的实时事务工作负荷。

行为说明

  • DML 操作不需要删除或重新生成向量索引。
  • 事务提交后，矢量搜索查询可以看到更改。
  • 对于大规模数据替换（例如，删除大多数行并插入一组全新的嵌入），请考虑在数据加载后删除和重新创建矢量索引，以确保最佳的搜索质量。

注释

DML 支持仅适用于使用最新版本创建的向量索引。 早期版本要求表是只读的，或使用 ALLOW_STALE_VECTOR_INDEX 数据库范围的配置。

监视矢量索引维护

矢量索引执行后台维护以合并 DML 更改。 使用 sys.dm_db_vector_indexes 动态管理视图监视索引运行状况和维护任务状态。

将矢量索引与传统索引相结合

矢量索引与传统的 B 树索引一起工作，以提供最佳的查询性能。 使用迭代筛选时 VECTOR_SEARCH，请考虑对筛选器谓词中使用的列创建传统索引。

有关迭代筛选行为及其与早期版本有何不同的详细信息，请参阅 迭代筛选行为。

小窍门

查询优化器会自动选择最佳执行策略（近似最近的邻居索引与 kNN 搜索）。 若要强制使用近似邻近索引，请使用 FORCE_ANN_ONLY 表提示。 有关详细信息，请参阅 矢量搜索的表提示。

示例方案：

-- Create vector index for similarity search
CREATE VECTOR INDEX idx_embeddings_vector
ON product_embeddings(embedding)
WITH (METRIC = 'cosine');

-- Create traditional index for filter columns
CREATE NONCLUSTERED INDEX idx_embeddings_filters
ON product_embeddings(category);

性能优势：

使用迭代筛选执行查询时，SQL Server 查询优化器使用这两种索引类型：

DECLARE @qv VECTOR(1536) = AI_GENERATE_EMBEDDINGS(N'wireless headphones' USE MODEL EmbeddingModel);

SELECT TOP (10) WITH APPROXIMATE
    p.name,
    p.price,
    vs.distance
FROM products p
INNER JOIN VECTOR_SEARCH(
    TABLE = product_embeddings AS e,
    COLUMN = embedding,
    SIMILAR_TO = @qv,
    METRIC = 'cosine'
) AS vs ON p.id = e.product_id
WHERE e.approved = 1             
  AND e.category = 'Electronics'  -- Can use traditional index
ORDER BY vs.distance;

在本查询中：

  • 矢量索引基于查询向量标识类似的嵌入
  • 在迭代搜索过程中有效筛选候选项的传统索引(category)

与仅使用矢量索引相比，此复合策略可以显著提高查询性能，尤其是在筛选器谓词具有较高的选择性时。

矢量索引的数据质量和维护指南

避免具有高重复嵌入的数据集

嵌入表示多种语义内容时，矢量索引效果最佳。 不要使用重复向量比例较高的数据集进行向量索引。

高重复可能导致：

  • 结果质量不佳：重复矢量在结果中反复出现，挤满了更相关的语义匹配项。
  • 降低有效性：重复嵌入会取代更好的邻居，降低相似性搜索的有用性。
  • 不必要的资源使用：矢量索引生成和维护成本昂贵，且无需增加价值即可重复添加成本。

最佳做法：在创建向量索引之前删除重复数据，以提高性能和结果质量。

大规模数据替换方案

矢量索引支持插入、更新和删除。 然而，当你替换大部分或全部嵌入——例如用新模型重新嵌入数据集时——现有索引可能不再反映新的数据分布。

在大规模替换方案中：

  • 向量搜索查询依然能返回有效结果。
  • 回忆和排名质量可能会下降，因为指数结构是为不同的嵌入分布设计的。

最佳做法：执行近乎完整的数据替换（删除并插入新嵌入），加载新数据后删除并重新创建矢量索引。 重新创建索引可确保它针对新的嵌入分发进行优化，并还原可预测的查询行为。

已知问题

有关详细信息，请查看 已知问题。

权限

你需要 ALTER 在桌子上获得许可。

例子

下载并导入 包含矢量嵌入示例的维基百科文章 。

这些示例假设有一个表， wikipedia_articles 表中有一列 title_vector 类型 vector ，存储维基百科条目的标题嵌入。 它 title_vector 使用了类似 文本嵌入-ada-002 或 文本嵌入-3-small的嵌入模型，返回维度为1,536的向量。

更多示例，包括端到端解决方案，请参见 Azure SQL 数据库 向量搜索示例 GitHub 仓库。

示例 1

以下示例使用title_vector指标对cosine列创建向量索引。

CREATE VECTOR INDEX vec_idx
    ON [dbo].[wikipedia_articles] ([title_vector])
        WITH (METRIC = 'COSINE', TYPE = 'DISKANN');

示例 2

以下示例利用（负）dot积度量在列title_vector上创建向量索引。 它将并行度限制为8，并将向量存储在 SECONDARY 文件组中。

CREATE VECTOR INDEX vec_idx
    ON [dbo].[wikipedia_articles] ([title_vector])
        WITH (METRIC = 'DOT', TYPE = 'DISKANN', MAXDOP = 8)
    ON [SECONDARY];

示例 3

本例使用 CREATE VECTOR INDEX 了 和 相关的 VECTOR_SEARCH 函数。 将模拟嵌入内容。 在现实场景中，可以通过嵌入模型和 AI_GENERATE_EMBEDDINGS生成嵌入，或使用外部库如 OpenAI SDK。

注释

最新版本的向量索引至少需要100行数据才能创建索引。 此示例插入 100 行以满足此要求。 有关详细信息，请参阅 最低数据要求。

以下代码块演示 CREATE VECTOR INDEX 了模拟嵌入：

  1. 启用预览功能（仅适用于 SQL Server 2025;Azure SQL 数据库 或 Fabric 中的 SQL 数据库则不需要）。
  2. 使用数据类型dbo.Articles的列embedding创建示例表。
  3. 使用模拟嵌入数据插入 100 行示例数据。
  4. 在 . 上 dbo.Articles.embedding创建向量索引。
  5. 使用函数演示矢量相似性搜索 VECTOR_SEARCH 。
-- Step 0: Enable Preview Feature (SQL Server 2025 only)
ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;
GO

-- Step 1: Create a sample table with a VECTOR(5) column
CREATE TABLE dbo.Articles
(
    id INT PRIMARY KEY,
    title NVARCHAR(100),
    content NVARCHAR(MAX),
    embedding VECTOR(5) -- mocked embeddings
);
GO

-- Step 2: Insert sample data (100 rows required for latest version indexes)
INSERT INTO Articles (id, title, content, embedding)
SELECT
    value AS id,
    'Article ' || [value],
    'Content for article ' || [value],
    CAST(JSON_ARRAY(
        CAST(value * 0.01 AS FLOAT),
        CAST(value * 0.02 AS FLOAT),
        CAST(value * 0.03 AS FLOAT),
        CAST(value * 0.04 AS FLOAT),
        CAST(value * 0.05 AS FLOAT)
    ) AS VECTOR(5))
FROM GENERATE_SERIES(1, 100);
GO

-- Step 3: Create a vector index on the embedding column
CREATE VECTOR INDEX vec_idx ON Articles(embedding)
WITH (METRIC = 'cosine', TYPE = 'diskann');
GO

-- Step 4: Perform a vector similarity search
DECLARE @qv VECTOR(5) = '[0.3, 0.3, 0.3, 0.3, 0.3]';
SELECT TOP(3) WITH APPROXIMATE
    t.id,
    t.title,
    t.content,
    s.distance
FROM
    VECTOR_SEARCH(
        TABLE = Articles AS t,
        COLUMN = embedding,
        SIMILAR_TO = @qv,
        METRIC = 'cosine'
    ) AS s
ORDER BY s.distance, t.title;

查询的语法取决于矢量索引版本：

矢量索引版本 语法示例
最新版本 不使用SELECT TOP (N) WITH APPROXIMATETOP_N参数
早期版本（已弃用） 在 TOP_N 函数中使用 VECTOR_SEARCH 参数

对于早期版本索引（已弃用的语法）：

DECLARE @qv VECTOR(5) = '[0.3, 0.3, 0.3, 0.3, 0.3]';
SELECT TOP(3)
    t.id,
    t.title,
    t.content,
    s.distance
FROM
    VECTOR_SEARCH(
        TABLE = Articles AS t,
        COLUMN = embedding,
        SIMILAR_TO = @qv,
        METRIC = 'cosine',
        TOP_N = 3
    ) AS s
ORDER BY s.distance, t.title;

示例 4：使用 DML 操作

以下示例展示了使用最新版本创建的向量索引表上的 DML 操作。

删除行

删除行会从表和矢量搜索结果中删除它们。

DELETE FROM dbo.wikipedia_articles
WHERE id = 12345;

删除操作结束后，移除的行将不再出现在向量搜索查询中。

插入新行

可以使用嵌入插入插入新行，无需重新生成索引即可立即搜索这些行。

INSERT INTO dbo.wikipedia_articles (id, title, title_vector)
VALUES (
    99999,
    N'Quantum Computing Basics',
    AI_GENERATE_EMBEDDINGS(N'Quantum Computing Basics' USE MODEL Ada2Embeddings)
);

新插入的嵌入内容会自动合并到矢量索引中，可由后续矢量搜索查询返回。

更新现有行

完全支持更新向量或非向量列。

DECLARE @new_embedding VECTOR(1536);
SET @new_embedding = AI_GENERATE_EMBEDDINGS(N'Updated article title' USE MODEL Ada2Embeddings);

UPDATE dbo.wikipedia_articles
SET title_vector = @new_embedding,
    title = N'Updated article title'
WHERE id = 50000;

如果你更新向量列，索引也会相应更新，以便未来的向量搜索使用新的嵌入。

复杂操作的应用MERGE

该 MERGE 语句允许在单个语句中执行插入、更新和删除操作。

MERGE INTO dbo.wikipedia_articles AS target
USING (
    SELECT 
        id,
        title,
        AI_GENERATE_EMBEDDINGS(title USE MODEL Ada2Embeddings) AS title_vector
    FROM dbo.staging_articles
) AS source
ON target.id = source.id
WHEN MATCHED THEN
    UPDATE SET 
        title = source.title,
        title_vector = source.title_vector
WHEN NOT MATCHED BY TARGET THEN
    INSERT (id, title, title_vector)
    VALUES (source.id, source.title, source.title_vector)
WHEN NOT MATCHED BY SOURCE AND target.id > 100000 THEN
    DELETE;

向量索引会自动更新，以反映语句所做的 MERGE 所有更改。

相关内容

  • Last updated on