REBUILD_INDEX

Use the DBMS_VECTOR.REBUILD_INDEX procedure to rebuild a vector index.

Purpose

To rebuild a vector index such as Hierarchical Navigable Small World (HNSW) vector index or Inverted File Flat (IVF) vector index. If idx_rebuild_mode is passed as non-NULL, the index is rebuilt using HNSW refresh support. If it is passed as NULL, the index is dropped and then recreated using the new index parameters.

Syntax

DBMS_VECTOR.REBUILD_INDEX (
    idx_name                   IN VARCHAR2,
    table_name                 IN VARCHAR2 DEFAULT NULL,
    idx_vector_col             IN VARCHAR2 DEFAULT NULL, 
    idx_include_cols           IN VARCHAR2 DEFAULT NULL,
    idx_partitioning_scheme    IN VARCHAR2 DEFAULT NULL,
    idx_organization           IN VARCHAR2 DEFAULT NULL,
    idx_distance_metric        IN VARCHAR2 DEFAULT NULL,
    idx_accuracy               IN NUMBER   DEFAULT NULL,
    idx_parameters             IN CLOB     DEFAULT NULL,
    idx_parallel_creation      IN NUMBER   DEFAULT NULL,
    idx_rebuild_mode           IN VARCHAR2 DEFAULT NULL,
    idx_quantization_type      IN VARCHAR2 DEFAULT NULL,
    idx_compression_ratio      IN NUMBER   DEFAULT NULL,
    idx_distribute_parameters  IN CLOB     DEFAULT NULL,
    idx_duplicate_parameters   IN CLOB     DEFAULT NULL,
    idx_online_build           IN BOOLEAN  DEFAULT NULL,
    idx_owner                  IN VARCHAR2 DEFAULT NULL
);

Parameters

Parameter Description

idx_name

Name of the index to rebuild.

table_name

Table on which to create the index.

idx_vector_col

Vector column on which to create the index.
idx_include_cols

A comma-separated list of column names to be covered by the index.

idx_partitioning_scheme

Partitioning scheme for IVF indexes:

  • GLOBAL

  • LOCAL

IVF indexes support both global and local indexes on partitioned tables. By default, these indexes are globally partitioned by centroid. You can choose to create a local IVF index, which provides a one-to-one relationship between the base table partitions or subpartitions and the index partitions.

For detailed information on these partitioning schemes, see Inverted File Flat Vector Indexes Partitioning Schemes.

idx_organization

Index organization:

  • NEIGHBOR PARTITIONS

  • INMEMORY NEIGHBOR GRAPH

For detailed information on these organization types, see Manage the Different Categories of Vector Indexes.

idx_distance_metric

Distance metric or mathematical function used to compute the distance between vectors:

  • COSINE
  • MANHATTAN
  • HAMMING
  • JACCARD
  • DOT
  • EUCLIDEAN
  • L2_SQUARED
  • EUCLIDEAN_SQUARED

For detailed information on each of these metrics, see Vector Distance Functions and Operators.

idx_accuracy

Target accuracy at which the approximate search should be performed when running an approximate search query.

As explained in Understand Approximate Similarity Search Using Vector Indexes, you can specify non-default target accuracy values either by specifying a percentage value or by specifying internal parameters values, depending on the index type you are using.

  • For an HNSW approximate search:

    In the case of an HNSW approximate search, you can specify a target accuracy percentage value to influence the number of  candidates considered to probe the search. This is automatically calculated by the algorithm. A value of 100 will tend to impose a similar result as an exact search, although the system may still use the index and will not perform an exact search. The optimizer may choose to still use an index as it may be faster to do so given the predicates in the query. Instead of specifying a target accuracy percentage value, you can specify the EFSEARCH parameter to impose a certain maximum number of candidates to be considered while probing the index. The higher that number, the higher the accuracy.

    For detailed information, see Understand Hierarchical Navigable Small World Indexes.

  • For an IVF approximate search:

    In the case of an IVF approximate search, you can specify a target accuracy percentage value to influence the number of partitions used to probe the search. This is automatically calculated by the algorithm. A value of 100 will tend to impose an exact search, although the system may still use the index and will not perform an exact search. The optimizer may choose to still use an index as it may be faster to do so given the predicates in the query. Instead of specifying a target accuracy percentage value, you can specify the NEIGHBOR PARTITION PROBES parameter to impose a certain maximum number of partitions to be probed by the search. The higher that number, the higher the accuracy.

    For detailed information, see Understand Inverted File Flat Vector Indexes.

idx_parameters

Type of vector index and associated parameters.

Specify the indexing parameters in JSON format:

  • For HNSW indexes:

    • type: Type of vector index to create, that is, HNSW

    • neighbors: Maximum number of connections permitted per vector in the HNSW graph

    • efConstruction: Maximum number of closest vector candidates considered at each step of the search during insertion

    • offload_credential_name: The identifier of the credential that should be used when authenticating with the offload service of the Private AI Services Container. Typically, this should match the offload_credential_name used when the vector index was created (prefixed by a schema if the credential schema is not the same as the currently active user schema).

    • offload_url: The Private AI Services Container service endpoint for index creation.

    For example:

    {
    "type"                    : "HNSW", 
    "neighbors"               : 3, 
    "efConstruction"          : 4,
    "offload_credential_name" : "privateai",
    "offload_url"             : "https://<myprivateaiservicehostname>/v1/index"
}

    For detailed information on these parameters, see Hierarchical Navigable Small World Index Syntax and Parameters.

    For information about the Private AI Services Container vector index service, see Oracle Private AI Services Container User's Guide.

  • For IVF indexes:

    • type: Type of vector index to create, that is, IVF

    • partitions: Neighbor partition or cluster in which you want to divide your vector space

    For example:

    {
    "type"       : "IVF",
    "partitions" : 5
}

    For detailed information on these parameters, see Inverted File Flat Index Syntax and Parameters.

idx_parallel_creation

Number of parallel threads used for index construction.

idx_rebuild_mode

Supported values:

  • FULL: Perform a full rebuild.
  • INCREMENTAL: Perform an incremental build.

By default, this parameter is set to NULL.

This parameter is only supported for HNSW vector indexes.

idx_quantization_type

Optional replacement quantization type to apply to the rebuilt index.

The supported values are NULL, 'NONE', and 'SCALAR'.

idx_compression_ratio

Optional replacement compression ratio for a quantized vector index.

This is provided either as a numeric value or NULL and is only valid when quantization is enabled.

idx_distribute_parameters

Optional replacement distribution settings for a distributed HNSW vector index.

The value is provided as NULL or as a JSON CLOB that includes distribute_method and optionally a service_name. The following are supported as the value for distribute_method:

  • 'ROWID RANGE'
  • 'SIMILARITY'
  • 'PARTITION'
  • 'SUBPARTITION'
  • 'DISTRIBUTE'
  • 'AUTO'

This parameter is only supported for HNSW indexes and can only be used if idx_duplicate_parameters is passed as NULL.

idx_duplicate_parameters

Optional replacement duplication settings for a distributed HNSW vector index.

The value is expected to be either NULL or a JSON CLOB that includes duplicate_method and optionally a service_name. The value provided for duplicate_method must be 'ALL'.

This parameter is only supported for HNSW indexes and can only be used if idx_distribute_parameters is passed as NULL.

idx_online_build

Optional replacement online build setting to use when recreating the vector index.

The values accepted are TRUE, FALSE, and NULL. The default value is NULL.

idx_owner

Specify the owning schema of the index to be rebuilt. The index will be rebuilt in the same schema. Use the default value, NULL, if the index is present in the current schema.

Usage Notes

For all parameters besides idx_name, if the value is passed as NULL (the default), the procedure uses the same value that was used by the index before the rebuild.

Examples

  • Specify neighbors and efConstruction for HNSW indexes:

    BEGIN
  DBMS_VECTOR.REBUILD_INDEX(
    idx_name                 => 'v_hnsw_01', 
    table_name               => 'vpt01', 
    idx_vector_col           => 'EMBEDDING', 
    idx_include_cols         => NULL, 
    idx_partitioning_scheme  => NULL, 
    idx_organization         => 'INMEMORY NEIGHBOR GRAPH', 
    idx_distance_metric      => 'EUCLIDEAN', 
    idx_accuracy             => 95, 
    idx_parameters           => '{
                                  "type" : "HNSW",
                                  "neighbors" : 3,
                                  "efConstruction" : 4
                                }'
  );
END;
/

  • Specify the number of partitions for IVF indexes:

    BEGIN
  DBMS_VECTOR.REBUILD_INDEX(
    idx_name                => 'V_IVF_01', 
    table_name              => 'vpt01', 
    idx_vector_col          => 'EMBEDDING', 
    idx_include_cols        => NULL,
    idx_partitioning_scheme => NULL, 
    idx_organization        => 'NEIGHBOR PARTITIONS', 
    idx_distance_metric     => 'EUCLIDEAN', 
    idx_accuracy            => 95, 
    idx_parameters          => '{
                                 "type" : "IVF",
                                 "partitions" : 5
                               }'
  );
END;
/

  • To enable a full graph rebuild:

    BEGIN
  DBMS_VECTOR.REBUILD_INDEX(
    idx_name                => 'v_hnsw_01',     
    table_name              => 'vpt01', 
    idx_vector_col          => 'EMBEDDING', 
    idx_include_cols        => NULL, 
    idx_partitioning_scheme => NULL, 
    idx_organization        => 'INMEMORY NEIGHBOR GRAPH', 
    idx_distance_metric     => 'EUCLIDEAN', 
    idx_accuracy            => 95,
    idx_parameters          => '{
                                 "type" : "HNSW",
                                 "neighbors" : 3,
                                 "efConstruction" : 4
                               }',
    idx_rebuild_mode        => 'FULL'
  );
END;
/

  • Specify a scalar quantized HNSW index rebuild:

    BEGIN
  DBMS_VECTOR.REBUILD_INDEX(
    idx_name              => 'V_HNSW_01',
    idx_vector_col        => 'EMBEDDING',
    idx_quantization_type => 'SCALAR',
    idx_compression_ratio => 4,
    idx_parameters        => '{
                               "type" : "HNSW",
                               "neighbors" : 32,
                               "efConstruction" : 200,
                               "rescore factor" : 2,
                               "algorithm" : "uniform_quantization"
                             }'
  );
END;
/

Parent topic: DBMS_VECTOR