---
title: github-fill
description: ALTER_INDEX_PARAMS 说明 该存储过程从 V4.6.3 版本开始支持。 ALTER_INDEX_PARAMS 过程用于在线修改 HNSW 系列向量索引参数。如果修改的是构建参数，则触发异步分区级重建任务；仅修改查询或同步相关参数时，不触发索引重建。 语法 PROCEDURE ALTER_INDEX_P…
image: https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*OSPzQ6GUQF4AAAAAQHAAAAgAeiGDAQ/original
---
切换语言

- 中文站 - 简体中文
- International - English
- 日本站 - 日本語

文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*M1BcQZvbrRMAAAAAQGAAAAgAeiGDAQ/original) OceanBase AI 数据库V 4.6.3

# ALTER_INDEX_PARAMS

更新时间：2026-11-16 14:23:02

[编辑](https://github.com/oceanbase/oceanbase-database-ai/edit/V4.6.3/zh-CN/700.reference/600.pl-reference/1000.pl-system-package-mysql/17850.dbms-vector-mysql/900.alter-index-params-mysql.md)

#### 说明

该存储过程从 V4.6.3 版本开始支持。

`ALTER_INDEX_PARAMS` 过程用于在线修改 HNSW 系列向量索引参数。如果修改的是构建参数，则触发异步分区级重建任务；仅修改查询或同步相关参数时，不触发索引重建。

## 语法

```sql
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` | 混合搜索索引的周期同步间隔。   #### 注意    仅在 `ASYNC` 模式下生效。在 `MANUAL` 或 `IMMEDIATE` 模式下也可保留或显式设置该参数，供后续切换至 `ASYNC` 模式时使用。 | 仅更新参数配置，不触发重建。 |

## 使用说明

#### 注意

将索引类型从 `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'` 筛选参数修改的后台任务：

```sql
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](#相关文档) 中查看其历史记录和执行结果：

```sql
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`：

```sql
ALTER SYSTEM CANCEL TASK '<TRACE_ID>';

```

取消时请注意：

- 取消为异步操作。命令成功返回仅表示取消请求已发出，不表示所有关联子任务均已退出或资源已清理完毕。尚未开始的子任务会被取消；已经执行的子任务收到取消请求后，按各自执行阶段退出并清理资源。
 - 取消不会回退已提交的索引参数配置，也不会撤销已完成的 Segment 更新。取消后，不同数据段可能保留不同的参数配置，不能再预期该任务会自动完成全部数据段的更新。可通过 `SEGMENT_PARAMS` 查看各数据段实际使用的参数。

## 示例

以下示例假设表 `t_document` 上已创建 HNSW 向量索引 `idx_embedding`。

仅修改查询参数，不触发索引重建：

```sql
CALL DBMS_VECTOR.ALTER_INDEX_PARAMS(
    'idx_embedding',
    't_document',
    'ef_search=128'
);

```

修改构建参数，并指定异步重建并行度为 `8`：

```sql
CALL DBMS_VECTOR.ALTER_INDEX_PARAMS(
    'idx_embedding',
    't_document',
    'm=32,ef_construction=300',
    8
);

```

同时修改构建参数和查询参数：

```sql
CALL DBMS_VECTOR.ALTER_INDEX_PARAMS(
    'idx_embedding',
    't_document',
    'm=40,ef_search=128',
    8
);

```

切换到 HNSW_BQ 索引：

```sql
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
);

```

使用完整限定名，表和索引的数据库名不一致时，调用会失败：

```sql
CALL DBMS_VECTOR.ALTER_INDEX_PARAMS(
  'vector_app.idx_embedding',
  'vector_app.t_document',
  'ef_search=128'
);

```

修改混合 HNSW 索引的同步配置。不触发索引重建，也不影响正在执行的构建参数修改任务。以下示例将同步模式设为 `MANUAL`，并设置同步间隔为 `30s`；该间隔仅在后续切换为 `ASYNC` 模式后生效：

```sql
CALL DBMS_VECTOR.ALTER_INDEX_PARAMS(
  'idx_document_vector',
  'documents',
  'sync_mode=MANUAL,sync_interval=30s'
);

```

## 相关文档

- [REBUILD_INDEX](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000007090378)
 - [DBA_OB_VECTOR_INDEX_TASKS](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000007089970)
 - [DBA_OB_VECTOR_INDEX_TASK_HISTORY](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000007090126)
 - [HNSW 系列索引](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000007089029)
 - [GV$OB_HNSW_INDEX_SEGMENT_INFO](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000007089887)

 上一篇 下一篇 ![有帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*y6ocSqN8cqsAAAAAAAAAAAAAARQnAQ)![无帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*BG9IQJyLHF8AAAAAAAAAAAAAARQnAQ)![反馈](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*eTWdQKCRKHwAAAAAAAAAAAAAARQnAQ)[AI](https://www.oceanbase.com/obi) 咨询热线
