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 requires these top-level fields at build time:

Field	Values	Description
`dim`	positive integer	Vector dimensionality; cannot change after build
`dtype`	`float32` / `fp16` / `bf16` / `int8`	Vector data type; determines internal representation
`metric_type`	`l2` / `ip` / `cosine`	Distance metric

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
    }
}

Field	Typical	Description
`max_degree`	16–48	Maximum out-degree per node
`ef_construction`	200–500	Candidate set size during build; larger = higher recall, slower build
`base_quantization_type`	`fp32` / `fp16` / `bf16` / `sq8` / `sq4` / `pq`	Quantization of the base storage — see the Quantization chapter for all supported values

At search time:

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

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
        }
    }
}

Field	Typical	Description
`transition_threshold`	`1000` or workload-specific	Positive vector count at which the index converts from exact flat search to HGraph
`hgraph`	HGraph build object	Parameters for the graph phase; see HGraph

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:

Parameter	Type	Default	Description
`skip_ratio`	float	`0.2`	Controls the ratio of filtered-search candidate checks to skip, in range `[0.0, 1.0]`. Higher values mean more aggressive skipping, faster search, and potentially lower recall.
`skip_strategy`	string	`"deterministic_accumulative"`	Skip strategy. Supports `"random"` and `"deterministic_accumulative"`.

IVF

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

Brute Force

{"brute_force": {}}

No extra parameters.

Pyramid

Pyramid supports organising multiple subgraphs by tag:

{
    "pyramid": {
        "tag_dim": 1,
        "max_degree": 24,
        "ef_construction": 300
    }
}

SINDI (sparse vectors)

{
    "sindi": {
        "top_k": 32,
        "doc_prune_ratio": 0.1
    }
}

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.

Keyboard shortcuts

VSAG Documentation