Index Parameters

This page summarises the commonly used parameters for every VSAG index type. For the full enumeration, consult the source:

• Build parameter keys: src/constants.cpp
• Public constants: include/vsag/constants.h
• Per-index examples: the examples/cpp/*_index_*.cpp files (e.g. 103_index_hgraph.cpp).

Common Fields

Every index accepts these top-level fields at build time. dtype and metric_type are required; repr is optional. dim is required for non-sparse data and defaults to 4096 for dtype: "sparse" when omitted:

dtype and repr describe different properties: dtype is the scalar encoding, while repr is the record layout. dtype: "sparse" requires repr: "sparse" when repr is explicit. Use repr: "multi_vector" with a supported multi-vector index and a scalar dtype such as float32.

HGraph

HGraph places its build parameters under the generic index_param key (see examples/cpp/103_index_hgraph.cpp); the hgraph key is reserved for search-time parameters.

{
    "dim": 128,
    "dtype": "float32",
    "metric_type": "l2",
    "index_param": {
        "base_quantization_type": "fp32",
        "max_degree": 32,
        "ef_construction": 400
    }
}

For HGraph float32 L2/IP/cosine, sq8_local and sq4_local can select either base_quantization_type or precise_quantization_type (the latter requires use_reorder: true). See local SQ4/SQ8 for memory, persistence and limitations.

PiPNN build parameters

When graph_type is pipnn, HGraph and Pyramid also accept the following build parameters under index_param. They share these defaults and validation rules:

The existing alpha field controls PiPNN’s final robust pruning. ef_construction only tunes NSW and has no effect on PiPNN.

At search time:

{"hgraph": {"ef_search": 100}}

ef_search accepts any positive signed 64-bit integer. It is no longer capped relative to topk; very large values can substantially increase latency and memory used by the frontier. use_conjugate_graph_search is a boolean (default true) that uses learned conjugate edges when the index was built with use_conjugate_graph: true.

The hgraph search-param object also accepts brute_force_threshold (a float in [0.0, 1.0], default 0.0). When set above zero and the request carries a filter whose ValidRatio() is at most this threshold, HGraph skips the graph traversal and runs an exact scan over the surviving ids. See the HGraph index page for details.

LazyHGraph

LazyHGraph can take its build parameters in a top-level lazy_hgraph object (preferred for clarity) or in the generic index_param object. The hgraph sub-object is forwarded to the internal HGraph used after transition.

{
    "dim": 128,
    "dtype": "float32",
    "metric_type": "l2",
    "lazy_hgraph": {
        "transition_threshold": 1000,
        "hgraph": {
            "base_quantization_type": "sq8",
            "max_degree": 26,
            "ef_construction": 100
        }
    }
}

LazyHGraph only supports dtype: "float32". Search parameters use the hgraph object, for example {"hgraph": {"ef_search": 100}}. See the LazyHGraph index page for details.

The hgraph search-param object also accepts the following filter-related parameters:

IVF

{
    "ivf": {
        "nlist": 4096,
        "base_quantization_type": "sq8",
        "nprobe": 32
    }
}

Brute Force

{"brute_force": {}}

No extra parameters.

Pyramid

Pyramid build parameters also live under index_param:

{
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 128,
    "index_param": {
        "base_quantization_type": "sq8",
        "max_degree": 24,
        "ef_construction": 300,
        "store_paths": true
    }
}

For graph_type: "pipnn", see the shared PiPNN build parameters above.

store_paths is a top-level Pyramid build parameter and defaults to false. Enable it when GetDataByIdsWithFlag must return the original default or named-hierarchy paths with DATA_FLAG_PATH; see the Pyramid parameter table for its completeness and persistence semantics.

MRLE with split RaBitQ uses base_quantization_type: "tq", tq_chain: "mrle, rabitq", mrle_dim, and the rabitq_bits_per_dim_base/rabitq_bits_per_dim_precise pair. It automatically reorders from the split base codes and retains original FP32 vectors for decode-only operations. See the Pyramid page for a complete configuration and storage/recall tradeoffs.

SINDI (sparse vectors)

{
    "dtype": "sparse",
    "metric_type": "ip",
    "dim": 1024,
    "index_param": {
        "term_id_limit": 30000,
        "doc_prune_ratio": 0.1
    }
}

See the SINDI page for use_quantization, immutable builds, and search parameters such as n_candidate.

SINDI_V2 (sparse vectors)

SINDI_V2 supports all SINDI features with both in-memory and disk-based I/O.

{
    "dtype": "sparse",
    "metric_type": "ip",
    "dim": 1024,
    "index_param": {
        "term_id_limit": 30000,
        "use_reorder": true,
        "term_io": {
            "type": "async_io",
            "file_path": "/path/to/sindi_v2.terms"
        },
        "rerank_io": {
            "type": "async_io",
            "file_path": "/path/to/sindi_v2.rerank"
        }
    }
}

See the SINDI_V2 page for build parameters and search parameters such as n_candidate and filter_callback_limit.

Runtime Parameters

Beyond build-time parameters, Index::Tune and SearchParam tweak runtime settings such as ef_search and nprobe. See Optimizer and the examples/cpp/3xx_feature_*.cpp examples.