索引监控与维护

本文档介绍了如何监控和维护 OceanBase 向量索引。

监控

通过系统视图可以查看向量索引的基本信息和实时状态。

基础维护

增量数据过多的情况下，搜索性能会下降。为减小增量数据表的数据量，OceanBase 数据库引入了 DBMS_VECTOR 对向量索引进行维护。

全量刷新（重建）

手动全表重建

如果建立索引后更新或删除数据较多，建议使用 REBUILD_INDEX 过程进行全量刷新。说明和示例请参见 REBUILD_INDEX。

默认情况下，全量刷新每 24 小时检查一次；若新增数据超过原有数据的 20%，则自动执行全量刷新。全量刷新会在后台异步执行，首先创建新的索引，然后替换旧索引。在重建过程中，旧索引保持可用状态，但整体过程相对较慢。

我们还提供了 vector_index_memory_saving_mode 配置项来控制索引重建的内存占用。开启此模式可以降低分区表向量索引重建（rebuild）过程中的内存消耗。通常，向量索引重建需要消耗相当于索引两倍的内存。开启省内存模式后，系统会在分区表单个分区构建完成后，通过暂时删除该分区的内存索引来释放内存，从而有效降低重建操作所需的总内存。语法和示例请参见vector_index_memory_saving_mode。

注意事项如下：

• 执行 离线 DDL 操作（例如 ALTER TABLE 修改表结构或主键）时，将导致索引表的重建。由于重建索引无法指定并行度，系统会默认使用单线程，因此在数据量较大时，重建过程会比较缓慢，从而影响整个 离线 DDL 的执行效率。

• 重建索引时如果需要修改索引参数，必须在参数列表中同时指定 type 和 distance，且 type 和 distance 必须和原索引类型一致，例如原来索引类型是 hnsw，距离算法是 l2，则重建时必须同时指定 type=hnsw 和 distance=l2。

• 重建索引时支持：

  • 修改 m，ef_search，ef_construction 值。
  • 在线重建 ef_search 参数。
  • hnsw <-> hnsw_sq 的索引类型重建。
  • ivf_flat <-> ivf_flat，ivf_pq <-> ivf_pq 的索引类型重建。
  • 支持重建时设置并行度。示例见 REBUILD_INDEX。

• 重建索引时不支持：

  • 修改 type 和 distance 类型。
  • hnsw <-> ivf 的索引重建。
  • hnsw <-> hnsw_bq 的索引重建。
  • ivf_flat，ivf_pq 之间的交叉重建。

配置重建参数

如果遇到合并窗口过多或者业务高峰期，可能会因为资源调度冲突导致重建失败，这时可以通过 DBMS_VECTOR.SET_ATTRIBUTE PL 系统包为索引配置重建的触发周期，避开合并窗口或业务高峰。

通过 SET_ATTRIBUTE 可为单个向量索引设置自动重建的并行度、触发阈值与触发周期：

-- 设置 rebuild 并行度
CALL DBMS_VECTOR.SET_ATTRIBUTE('idx1', 't1', 'parallel', '20');

-- 设置 rebuild 触发阈值（增量数据达到基线 50% 时触发）
CALL DBMS_VECTOR.SET_ATTRIBUTE('idx1', 't1', 'rebuild_trigger_percentage', '0.5');

-- 设置 rebuild 触发周期：每 600 秒检查一次
CALL DBMS_VECTOR.SET_ATTRIBUTE('idx1', 't1', 'rebuild_repeat_interval', 'FREQ=SECONDLY; INTERVAL=600');

-- 设置 rebuild 触发周期：每天 19:45:00 检查
CALL DBMS_VECTOR.SET_ATTRIBUTE('idx1', 't1', 'rebuild_repeat_interval', 'FREQ=DAILY; byhour=19;byminute=45;bysecond=0');

使用时的注意事项如下：

• 不同索引的 rebuild_repeat_interval 应错开，避免同一时段集中重建。

参数说明、约束和示例请参见 SET_ATTRIBUTE。

自动分区重建（推荐）

当前版本会触发自动分区重建任务的场景有两种：

• 执行向量索引搜索语句时。
• 定时检查，可手动配置执行周期。

1. 配置执行周期

   在 oceanbase 数据库下，通过配置项 vector_index_optimize_duty_time 配置执行周期。示例如下：

   ALTER SYSTEM SET vector_index_optimize_duty_time='[23:00:00, 24:00:00]';
   

   如上配置完成后，分区重建任务只会在 23:00:00~24:00:00 时间段执行，其他时间段里不会发起。详细参数说明参见相应配置项文档。

2. 查看任务进展/历史任务

   可通过 CDB/DBA_OB_VECTOR_INDEX_TASKS 或 CDB/DBA_OB_VECTOR_INDEX_TASK_HISTORY 视图查看任务进展和历史任务，相关视图说明请参见文末相关文档。

   注意

   上述视图涵盖分区重建、Segment 转储与合并、IVF 聚类中心加载与清理、语义索引刷新、内存同步等向量索引后台任务，可通过视图中的 TASK_TYPE 字段区分任务类型。

   通过 STATUS 字段判断任务当前状态：

   • PREPARE：任务等待执行。
   • RUNNING：任务正在执行中。
   • PENDING：任务暂停执行。
   • FINISHED：任务已完成。
   • STANDBY：手动触发的任务等待节点认领并执行。
   • QUEUE：任务在优先级队列中排队等待执行。
   • CANCEL：任务已被取消。
   • EXCHANGE：新旧索引交换中（此状态为自动分区重建任务的特有状态）。
   • CLEAN：资源清理中（此状态为自动分区重建任务的特有状态）。

   执行结束的任务，即状态为 FINISHED 的任务，无论是否执行成功都会被转存到历史表。详细使用示例请参见相应视图文档。

3. 取消任务

   如需取消任务，可通过 DBA_OB_VECTOR_INDEX_TASKS 或 CDB_OB_VECTOR_INDEX_TASKS 视图获取 trace_id 后，执行以下命令（相关视图说明请参见文末相关文档）：

   ALTER SYSTEM CANCEL TASK <trace_id>;
   

   示例如下：

   ALTER SYSTEM CANCEL TASK "Y61480BA2D976-00063084E80435E2-0-1";
   

专项维护

手动强制转储/合并（备选）

增量段（Segment）的转储与合并流程通常由数据库系统后台模块在满足特定条件时自动触发。OceanBase 支持以下手动触发方式：

• 表级触发：通过 DBMS_VECTOR 系统包中的 FLUSH_INDEX 和 COMPACT_INDEX 过程，在表/索引粒度上强制触发转储和合并任务。语法和示例请参见 FLUSH_INDEX 和 COMPACT_INDEX。
• Tablet 级触发：通过 DBMS_VECTOR 系统包中的 TRIGGER_ASYNC_TASK 存储过程，通过指定任务类型与 tablet_id 手动创建向量索引后台任务，支持增量 Segment 冻结、合并及 Follower 内存加载等类型。语法和示例请参见 TRIGGER_ASYNC_TASK。

触发后，可以查询 DBA_OB_VECTOR_INDEX_TASKS，其中 TASK_TYPE='INCREMENTAL_INDEX_FREEZE' 为触发的转储任务，TASK_TYPE='INCREMENTAL_INDEX_MERGE' 为触发的合并任务。如果当前增量数据量较小，任务可能很快完成，此时可以查看历史任务视图 DBA_OB_VECTOR_INDEX_TASK_HISTORY。如果数据量较大，合并过程可能耗时较长，可通过 GV$SESSION_LONGOPS 视图实时查看执行进度。查询示例和详细说明请参见相应视图文档。

Segment 是向量索引中用于组织分区内存数据的基本单元，负责管理增量数据的存储与合并。详细概念介绍和阈值控制方法请参见文末相关文档"向量索引内存管理"。

后台任务优先级调度

向量后台任务共用一个线程池，系统按 6 级优先级（P0–P5）调度：影响前台服务的任务优先，轻量资源清理次之，重操作中等优先级，后台重任务最低。默认优先级与水位阈值如下：

水位阈值表示：当前正在运行的任务数占线程池总线程数的百分比。只有当运行中任务的水位低于该阈值时，该优先级及更低优先级的任务才会被调度。这样可保证高优先级任务始终有可用线程，低优先级任务不会占满全部线程。

若某类任务在特定租户或时段需要更激进或更保守的执行策略，可通过配置项 vector_task_thread_limit_percent 按任务类型覆盖默认调度水位。例如，在业务高峰期降低 Segment 转储、合并任务的调度比例以减轻资源争用：

ALTER SYSTEM SET vector_task_thread_limit_percent = 'INCREMENTAL_INDEX_FREEZE:30,INCREMENTAL_INDEX_MERGE:30';

详细取值格式与任务类型说明请参见相应配置项文档。

通过 cgroup 管控后台任务资源（可选）

向量后台任务已接入函数（Function）级资源隔离，可按任务类型限制 CPU、IO 占用，对应资源请求类型如下：

具体配置步骤请参见 后台任务的资源隔离配置案例 和 资源隔离概述。

查看内存限流信息

对于分区级索引重建、增量 Segment 合并等内存消耗较大的任务，调度器在触发执行前会检查租户向量内存是否充足。若当前内存不足，则暂缓调度该任务，将其保留在队列中，待其他任务释放内存后再执行，任务不会被丢弃。

任务完成后，内存限流相关信息会记录在历史任务视图 DBA_OB_VECTOR_INDEX_TASK_HISTORY（或 CDB_OB_VECTOR_INDEX_TASK_HISTORY）的 TASK_INFO 字段中，格式为 JSON，包含 mem_limit_info 段。相关视图说明及示例请参见文末相关文档。

小租户自适应线程池机制

为避免小规格租户因后台线程数过多而浪费资源，系统会根据租户 CPU 规格自适应计算向量后台任务线程池的最大线程数。本节说明其机制与计算公式。具体计算公式如下：

max_threads = clamp(floor(cpu × 0.5), 2, 64)

计算参数含义如下：

常见租户规格对应的最大线程数如下：

当租户 CPU 配额发生变更（如在线扩缩容）时，线程池规模会自动刷新，确保线程数与当前 CPU 规格匹配，无需手动干预。即使线程池较小，系统也会通过最小槽位保证机制，确保各优先级任务都能获得基本的调度机会。

相关文档

• 向量索引性能优化
• 增量 Segment 的自动转储合并可通过配置项控制阈值，详见向量索引内存管理
• CDB/DBA_OB_VECTOR_INDEX_TASKS
• CDB/DBA_OB_VECTOR_INDEX_TASK_HISTORY