Note
This stored procedure is supported starting from V4.6.3.
The ALTER_INDEX_PARAMS procedure is used to modify HNSW series vector index parameters online. If construction parameters are modified, an asynchronous partition-level rebuild task is triggered; if only query or synchronization-related parameters are modified, no index rebuild is triggered.
Syntax
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
);
Parameters
Parameter |
Required |
Description |
|---|---|---|
IDX_NAME |
Yes | The name of the vector index whose parameters need to be modified. |
TABLE_NAME |
Yes | The name of the data table to which the vector index belongs. |
IDX_PARAMETERS |
Yes | The index parameter to be modified. In the format of KEY=VALUE Format the parameters. Separate multiple parameters with commas (,), for example, 'M=32,EF_CONSTRUCTION=300', unspecified parameters are typically retained with their current values. For the handling rules of HNSW_BQ-specific parameters during index type switching, see the "Usage instructions" section below. The following table lists supported parameters. |
IDX_PARALLEL_BUILD |
No | The degree of parallelism for asynchronous rebuild tasks when class parameters change. Value range: 0 to 64. Default value: 0, which indicates that the degree of parallelism is adaptively set based on CPU resources. This parameter does not take effect when only query parameters are modified. |
IDX_PARAMETERS supports the following parameters:
Parameter |
Description |
Update behavior |
|---|---|---|
type |
HNSW series index type. | Triggers asynchronous partition-level rebuilding. |
m |
The maximum number of neighbors for each node in the HNSW graph. Value range: 5 to 128. |
Triggers asynchronous partition-level rebuilding. |
ef_construction |
The size of the candidate set during index construction. Value range: 5 to 1000. |
Triggers asynchronous partition-level rebuilding. |
ef_search |
The size of the candidate set during search. The supported value range is 1 to 160000. |
Only the parameter configuration is updated; a rebuild is not triggered. |
refine_type |
HNSW_BQ: Fine-grained scheduling type. | Triggers asynchronous partition-level rebuilding. |
bq_bits_query |
The number of quantization bits for HNSW_BQ queries. Valid values: 0, 4, or 32. |
Triggers asynchronous partition-level rebuilding. |
bq_use_fht |
Whether to use FHT for HNSW_BQ. Valid values: TRUE or FALSE. |
Triggers asynchronous partition-level rebuilding. |
refine_k |
Precisely round up the candidate multiples. Value range: 1 to 1000. |
Only the parameter configuration is updated; a rebuild is not triggered. |
sync_mode |
Data synchronization mode for hybrid search indexes. | Only the parameter configuration is updated; a rebuild is not triggered. |
sync_interval |
The periodic synchronization interval for hybrid search indexes.
NoticeEffective only in |
Only the parameter configuration is updated; a rebuild is not triggered. |
Usage instructions
Notice
When you change the index type from HNSW_BQ to HNSW or HNSW_SQ, the recall rate of vector search may decrease during the modification, causing some relevant results to be missed. Before performing such a modification, carefully evaluate its impact on your business search performance.
How parameter modifications take effect
- After you modify the build parameters, the system will rebuild indexes by partition in the background to gradually apply the new parameters. When the process call is completed, the rebuilding task may still be in progress, and some data segments may still use the parameters from before the modification. For example, if you change
mfrom16to32, some data segments may still usem=16until the rebuilding is complete. - You can view the parameters actually used by each data segment in the
SEGMENT_PARAMScolumn of [[G]V$OB_HNSW_INDEX_SEGMENT_INFO](#Related documents). - Whether
bq_bits_queryandbq_use_fht(exclusive parameters for the HNSW_BQ index type) are available depends on the index type after this modification. When switching to HNSW_BQ, you can set both the index type and its exclusive parameters in one call; when switching from HNSW_BQ to HNSW or HNSW_SQ, the system automatically removes these two parameters from the index configuration.
View and cancel background tasks
After modifying build parameters, the new parameters are gradually applied to each segment through background tasks. A return from the process call does not indicate that all modifications are complete. You can view the modification progress and execution status in the task view. If you need to stop ongoing modifications, an administrator can cancel the corresponding background task.
The specific instructions for different operations are as follows:
View modification progress
Query [DBA_OB_VECTOR_INDEX_TASKS](#Related topics) in the current tenant and filter background tasks that modify parameters by using 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;
This statement lists tasks of this type in the current tenant, which may include tasks generated by other index modifications or other modification operations.
After confirming the background task, you can use the STATUS statement to view the task status, and the TASK_INFO statement to view the modification progress and parameter configuration. The alter_index_params object contains the following fields:
progress: The overall progress of this parameter modification for each data tablet application, in the format of0%to100%.index_params: The complete index parameter configuration after this modification is committed, which includes not only the parameters specified during the call. The actual parameters used by each data segment may not have been fully updated.idx_parallel_build: The degree of parallelism used when a merge subtask builds physical indexes.old_index_params: The index parameter configuration before this modification.elapsed_time_s: The duration of task execution, in seconds.
If the background task has ended, you can view its history and execution results in [DBA_OB_VECTOR_INDEX_TASK_HISTORY](#Related topics):
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;
Cancel the background task for this modification
To stop a submitted but still-running modification of build parameters, the administrator should cancel the corresponding task. Canceling a task does not undo the committed index parameter configurations or completed segment updates; therefore, after cancellation, different parameter configurations may be used by each segment. When executing the following command, replace the placeholder with the TRACE_ID of the task queried from the previous operation:
ALTER SYSTEM CANCEL TASK '<TRACE_ID>';
Note that when you cancel:
- The operation is canceled asynchronously. A successful command return only indicates that the cancellation request has been sent, not that all associated subtasks have exited or resources have been cleaned up. Subtasks that have not yet started will be canceled; for those already in progress, they will exit and clean up resources at their current execution stage upon receiving the cancellation request.
- Canceling a task does not undo the submitted index parameter configurations or the completed segment updates. After cancellation, different data segments may retain different parameter configurations, and you cannot expect the task to automatically complete updates for all data segments. You can view the actual parameters used by each data segment using the
SEGMENT_PARAMScommand.
Examples
The following example assumes that the HNSW vector index idx_embedding has been created on table t_document.
Modifying query parameters only, without triggering index rebuilding:
CALL DBMS_VECTOR.ALTER_INDEX_PARAMS(
'idx_embedding',
't_document',
'ef_search=128'
);
Modify the build parameters and set the parallelism for asynchronous rebuild to 8:
CALL DBMS_VECTOR.ALTER_INDEX_PARAMS(
'idx_embedding',
't_document',
'm=32,ef_construction=300',
8
);
Modify both build parameters and query parameters:
CALL DBMS_VECTOR.ALTER_INDEX_PARAMS(
'idx_embedding',
't_document',
'm=40,ef_search=128',
8
);
Switch to the HNSW_BQ index:
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
);
Calls will fail if the database names of the table and index do not match when using fully qualified names:
CALL DBMS_VECTOR.ALTER_INDEX_PARAMS(
'vector_app.idx_embedding',
'vector_app.t_document',
'ef_search=128'
);
Modify the synchronization configuration for a hybrid HNSW index. This does not trigger index rebuilding and does not affect ongoing parameter modification tasks. The following example sets the synchronization mode to MANUAL and the synchronization interval to 30s; this interval only takes effect after switching to ASYNC mode later on:
CALL DBMS_VECTOR.ALTER_INDEX_PARAMS(
'idx_document_vector',
'documents',
'sync_mode=MANUAL,sync_interval=30s'
);