基于湖库一体架构,统一管理结构化、半结构化与非结构化等多模态数据,一个系统承载事务处理、实时分析与 AI 工作负载。
ALTER_INDEX_PARAMS
更新时间:2026-11-16 14:23:02
说明
该存储过程从 V4.6.3 版本开始支持。
ALTER_INDEX_PARAMS 过程用于在线修改 HNSW 系列向量索引参数。如果修改的是构建参数,则触发异步分区级重建任务;仅修改查询或同步相关参数时,不触发索引重建。
语法
PROCEDURE ALTER_INDEX_PARAMS(
IN IDX_NAME VARCHAR(65535),
IN TABLE_NAME VARCHAR(65535),
IN IDX_PARAMETERS LONGTEXT,
IN IDX_PARALLEL_BUILD INT DEFAULT 0
);
参数说明
| 参数 | 是否必选 | 说明 |
|---|---|---|
IDX_NAME |
是 | 需要修改参数的向量索引的名称。 |
TABLE_NAME |
是 | 向量索引所属的数据表名称。 |
IDX_PARAMETERS |
是 | 待修改的索引参数。以 KEY=VALUE 格式指定参数,多个参数之间使用英文逗号(,)分隔,例如 'M=32,EF_CONSTRUCTION=300',未指定的参数通常保留当前值;索引类型切换时,HNSW_BQ 专属参数的处理规则见下文“使用说明”。支持的参数见下表。 |
IDX_PARALLEL_BUILD |
否 | 构建类参数变化时,异步重建任务的并行度。取值范围为 0~64,默认值为 0,表示根据 CPU 资源自适应设置并行度。仅修改查询类参数时,此参数不生效。 |
IDX_PARAMETERS 支持以下参数:
| 参数 | 说明 | 更新行为 |
|---|---|---|
type |
HNSW 系列索引类型。 | 触发异步分区级重建。 |
m |
HNSW 图中每个节点的最大邻居数,取值范围为 5~128。 |
触发异步分区级重建。 |
ef_construction |
构建索引时的候选集大小,取值范围为 5~1000。 |
触发异步分区级重建。 |
ef_search |
搜索时的候选集大小,本过程支持的取值范围为 1~160000。 |
仅更新参数配置,不触发重建。 |
refine_type |
HNSW_BQ 精排类型。 | 触发异步分区级重建。 |
bq_bits_query |
HNSW_BQ 查询量化位数,可取 0、4 或 32。 |
触发异步分区级重建。 |
bq_use_fht |
HNSW_BQ 是否使用 FHT,可取 TRUE 或 FALSE。 |
触发异步分区级重建。 |
refine_k |
精排候选倍数,取值范围为 1~1000。 |
仅更新参数配置,不触发重建。 |
sync_mode |
混合搜索索引的数据同步模式。 | 仅更新参数配置,不触发重建。 |
sync_interval |
混合搜索索引的周期同步间隔。
注意仅在 |
仅更新参数配置,不触发重建。 |
使用说明
注意
将索引类型从 HNSW_BQ 修改为 HNSW 或 HNSW_SQ 时,修改期间向量搜索的召回率可能下降,导致部分相关结果未被搜索到。请评估对业务搜索效果的影响后,谨慎执行此类修改。
参数修改的生效方式
- 修改构建参数后,系统会在后台按分区重建索引,使新参数逐步生效。过程调用完成时,重建任务可能仍在执行,部分数据段仍使用修改前的参数。例如把
m从16改为32,重建完成前,部分数据段可能仍使用m=16。 - 可通过 [G]V$OB_HNSW_INDEX_SEGMENT_INFO 的
SEGMENT_PARAMS列查看各数据段实际使用的参数。 bq_bits_query和bq_use_fht(HNSW_BQ 索引专属参数)是否可用取决于本次修改后的索引类型。切换为 HNSW_BQ 时,可以同时设置索引类型及其专属参数,无需分两次调用;从 HNSW_BQ 切换为 HNSW 或 HNSW_SQ 时,系统会自动从索引配置中移除这两个参数。
查看和取消后台任务
修改构建参数后,新参数需要通过后台任务逐步应用到各 Segment,过程调用返回并不表示修改已全部完成。此时,可以通过任务视图查看修改进度和执行状态;如果需要停止仍在执行的修改,管理员可以取消对应的后台任务。
不同操作具体说明如下:
查看修改进度
在当前租户中查询 DBA_OB_VECTOR_INDEX_TASKS,通过 TASK_TYPE='ALTER_INDEX_PARAMS' 筛选参数修改的后台任务:
SELECT TABLE_ID, TABLET_ID, TASK_ID, CREATE_TIME, STATUS,
TASK_TYPE, TRIGGER_TYPE, TRACE_ID, TASK_INFO
FROM oceanbase.DBA_OB_VECTOR_INDEX_TASKS
WHERE TASK_TYPE = 'ALTER_INDEX_PARAMS'
ORDER BY CREATE_TIME DESC;
该语句列出当前租户中此类型的任务,可能包含其他索引或其他修改操作产生的任务。
确认后台任务后,可以通过 STATUS 查看任务状态,通过 TASK_INFO 查看修改进度和参数配置。其中,alter_index_params 对象包含以下字段:
progress:各数据分片(Tablet)应用本次参数修改的整体进度,格式为0%~100%。index_params:本次修改提交后的完整索引参数配置,不仅包含调用时指定的参数。各数据段实际使用的参数可能尚未全部更新。idx_parallel_build:合并(Merge)子任务构建物理索引时使用的并行度。old_index_params:本次修改前的索引参数配置。elapsed_time_s:任务执行时长,单位为秒。
如果后台任务已结束,可在 DBA_OB_VECTOR_INDEX_TASK_HISTORY 中查看其历史记录和执行结果:
SELECT TABLE_ID, TABLET_ID, TASK_ID, CREATE_TIME, STATUS,
TASK_TYPE, TRIGGER_TYPE, TRACE_ID, RET_CODE, ERR_MSG
FROM oceanbase.DBA_OB_VECTOR_INDEX_TASK_HISTORY
WHERE TASK_TYPE = 'ALTER_INDEX_PARAMS'
ORDER BY CREATE_TIME DESC;
取消本次修改的后台任务
如果需要停止已提交且仍在执行的构建参数修改,管理员应取消对应的任务。取消任务不会撤销已提交的索引参数配置或已完成的 Segment 更新,因此取消后,各 Segment 可能使用不同的参数配置。执行以下命令时,将占位符替换为上个操作查询出的任务 TRACE_ID:
ALTER SYSTEM CANCEL TASK '<TRACE_ID>';
取消时请注意:
- 取消为异步操作。命令成功返回仅表示取消请求已发出,不表示所有关联子任务均已退出或资源已清理完毕。尚未开始的子任务会被取消;已经执行的子任务收到取消请求后,按各自执行阶段退出并清理资源。
- 取消不会回退已提交的索引参数配置,也不会撤销已完成的 Segment 更新。取消后,不同数据段可能保留不同的参数配置,不能再预期该任务会自动完成全部数据段的更新。可通过
SEGMENT_PARAMS查看各数据段实际使用的参数。
示例
以下示例假设表 t_document 上已创建 HNSW 向量索引 idx_embedding。
仅修改查询参数,不触发索引重建:
CALL DBMS_VECTOR.ALTER_INDEX_PARAMS(
'idx_embedding',
't_document',
'ef_search=128'
);
修改构建参数,并指定异步重建并行度为 8:
CALL DBMS_VECTOR.ALTER_INDEX_PARAMS(
'idx_embedding',
't_document',
'm=32,ef_construction=300',
8
);
同时修改构建参数和查询参数:
CALL DBMS_VECTOR.ALTER_INDEX_PARAMS(
'idx_embedding',
't_document',
'm=40,ef_search=128',
8
);
切换到 HNSW_BQ 索引:
CALL DBMS_VECTOR.ALTER_INDEX_PARAMS(
'idx_embedding',
't_document',
'type=HNSW_BQ,refine_type=SQ8,bq_bits_query=4,bq_use_fht=TRUE,refine_k=8',
2
);
使用完整限定名,表和索引的数据库名不一致时,调用会失败:
CALL DBMS_VECTOR.ALTER_INDEX_PARAMS(
'vector_app.idx_embedding',
'vector_app.t_document',
'ef_search=128'
);
修改混合 HNSW 索引的同步配置。不触发索引重建,也不影响正在执行的构建参数修改任务。以下示例将同步模式设为 MANUAL,并设置同步间隔为 30s;该间隔仅在后续切换为 ASYNC 模式后生效:
CALL DBMS_VECTOR.ALTER_INDEX_PARAMS(
'idx_document_vector',
'documents',
'sync_mode=MANUAL,sync_interval=30s'
);