VSAG Documentation

VSAG is a high-performance, production-grade vector indexing library for similarity search. It powers vector retrieval in OceanBase and other projects at Ant Group, and is released under the Apache 2.0 license.

Features

• Multiple index types: hgraph, ivf, pyramid, sindi, sindi_v2, brute_force, covering in-memory, sparse and multi-tenant scenarios.
• Rich quantization: fp32 / fp16 / bf16 / int8 / sq8 / sq4 / pq, with SIMD dispatch on x86_64 and AArch64.
• Advanced capabilities: range search, filtered search, serialization, conjugate graph enhancement, online Tune-based optimization, custom allocator / thread pool.
• Language bindings: native C++, Python via pyvsag, Node.js / TypeScript via the npm package vsag.

How to Read This Documentation

• User Guide — start here if you are new to VSAG: install, create an index, and run search.
• Indexes — compare supported index types and look up their parameters.
• Advanced Features — deep dives into specific search, serialization, memory, and hybrid-index capabilities.
• API Reference — the C++ class, method, and type reference for the public headers in include/vsag/.
• Performance and Tuning — best practices, Tune, benchmarks, and evaluation tooling.
• Developer Guide — building from source, running tests, and contributing.
• Resources — release notes, roadmap, community links, related projects, papers, and contributors.

The Chinese version of the same documentation is available under docs/docs/zh/.

Project Links

• Source: https://github.com/antgroup/vsag
• Issues: https://github.com/antgroup/vsag/issues
• Releases: https://github.com/antgroup/vsag/releases

Installation

VSAG can be installed as a C++ library, a Python package (pyvsag), or a Node.js/TypeScript package (vsag).

Using Docker (Recommended for Development)

The official development image includes the full toolchain (GCC 9.4+, CMake 3.18+, clang-format/clang-tidy 15, HDF5, etc.):

docker pull vsaglib/vsag:ubuntu
docker run -it --rm -v $(pwd):/work -w /work vsaglib/vsag:ubuntu bash

Building from Source

Requirements

• Operating System: Ubuntu 20.04+, CentOS 7+, or macOS 14+ on Apple Silicon
• Compiler: GCC 9.4.0+, Clang 13.0.0+, or Apple Clang from Xcode Command Line Tools
• CMake: 3.18.0+
• clang-format / clang-tidy: exactly version 15 (enforced by make fmt / make lint)

Build

git clone https://github.com/antgroup/vsag.git
cd vsag
./scripts/deps/install_deps.sh
make release

The dependency script detects Linux versus macOS. On macOS it installs or locates the Homebrew dependencies and uses Apple’s Accelerate framework where appropriate. The supported macOS path is the arm64 C++ library build; published C++ archives and pyvsag wheels remain Linux-focused.

Other common Makefile targets:

• make debug — plain debug build (no sanitizers; tests/tools/examples disabled by default).
• make dev — developer configuration: debug + tests + tools + examples.
• make test — build with tests enabled and run the unit + functional suites.
• make cov — build with coverage instrumentation; run tests afterwards to generate the report.
• make asan / make tsan — sanitizer-enabled builds.
• make pyvsag PY_VERSION=3.10 — build the Python wheel.
• make dist-pre-cxx11-abi / dist-cxx11-abi / dist-libcxx — build redistributable tarballs.

See Building for details.

Python (pyvsag)

pip install pyvsag

Node.js / TypeScript

npm install vsag

The bindings source lives under typescript/ and the npm package name is vsag.

Optional Features

Enable or disable at CMake configure time with these cache options:

• ENABLE_INTEL_MKL=ON — Intel MKL acceleration.
• ENABLE_LIBAIO=ON — Linux AIO for the async_io data-cell backend.
• ENABLE_LIBURING=ON — Linux io_uring backend; requires liburing.
• ENABLE_TOOLS=ON — build tools under tools/ (including eval_performance).
• ENABLE_EXAMPLES=ON — build sample programs under examples/cpp/.

If you build through the project Makefile, the corresponding environment variables are VSAG_ENABLE_INTEL_MKL=ON, VSAG_ENABLE_LIBAIO=ON, VSAG_ENABLE_TOOLS=ON, and VSAG_ENABLE_EXAMPLES=ON. ENABLE_LIBURING is currently a direct CMake option; configure it with cmake -S . -B build-release -DENABLE_LIBURING=ON.

Creating an Index

All VSAG indexes are built through vsag::Factory::CreateIndex(name, build_params_json). The name selects the implementation; build_params_json configures dimension, metric, and index-specific options.

Supported Index Types

Common Top-Level Fields

Examples

HGraph

HGraph uses index_param as the build-time sub-object (hgraph is reserved for search-time parameters like ef_search). See examples/cpp/103_index_hgraph.cpp.

std::string params = R"(
{
    "dim": 128,
    "dtype": "float32",
    "metric_type": "l2",
    "index_param": {
        "base_quantization_type": "fp32",
        "max_degree": 32,
        "ef_construction": 400
    }
}
)";
auto index = vsag::Factory::CreateIndex("hgraph", params).value();

HGraph with SQ8 quantization

Switch base_quantization_type to sq8 to store base vectors as 8-bit scalar-quantized codes (roughly a 4× reduction versus fp32) with minimal recall impact; other quantization types (fp16, bf16, pq, …) are selected the same way.

std::string params = R"(
{
    "dim": 768,
    "dtype": "float32",
    "metric_type": "ip",
    "index_param": {
        "base_quantization_type": "sq8",
        "max_degree": 32,
        "ef_construction": 400
    }
}
)";
auto index = vsag::Factory::CreateIndex("hgraph", params).value();

SINDI_V2 with disk-based I/O

std::string params = R"(
{
    "dim": 1024,
    "dtype": "sparse",
    "metric_type": "ip",
    "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"
        }
    }
}
)";
auto index = vsag::Factory::CreateIndex("sindi_v2", params).value();

See Index Parameters for the full reference.

k-Nearest Neighbor Search

This page assumes VSAG is already installed. Examples are available in C++, Python, and TypeScript under the examples/ directory. This page uses the C++ BruteForce index for illustration; the full source is at examples/cpp/105_index_brute_force.cpp.

In most cases, your program should call vsag::init() once at startup to perform one-time initialization (global logger, allocator, etc.). The snippets below omit boilerplate to focus on the essential steps.

Prepare Vectors

VSAG operates on collections of fixed-dimensional vectors (typically a few hundred to a few thousand dimensions). Vectors are laid out row-major, equivalent to vector[num_vectors][dim] in C++. The API only requires a pointer (const float*) to the first element, so you can use a raw array, std::vector<float>, or a custom buffer.

VSAG currently supports 32-bit float vectors for the public API. Other dtypes are available internally via the dtype option.

A k-NN search needs two datasets:

• base: all vectors in the database; size = num_vectors * dim.
• query: the query vector(s) for which to find nearest neighbors; size = num_queries * dim. Currently the public KnnSearch API processes one query at a time.

int64_t num_vectors = 10000;
int64_t dim = 128;
int64_t* ids = new int64_t[num_vectors];
float* datas = new float[num_vectors * dim];
std::mt19937 rng(47);
std::uniform_real_distribution<float> distrib;
for (int64_t i = 0; i < num_vectors; ++i) ids[i] = i;
for (int64_t i = 0; i < dim * num_vectors; ++i) datas[i] = distrib(rng);

float* query_vector = new float[dim];
for (int64_t i = 0; i < dim; ++i) query_vector[i] = distrib(rng);

Create an Index and Insert Vectors

The Index interface is the central abstraction. Multiple implementations exist; brute_force is the simplest (exhaustive comparison, used as a baseline).

All indexes must be created explicitly, specifying dimension and metric:

std::string build_params = R"(
{
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 128
}
)";
auto index = vsag::Factory::CreateIndex("brute_force", build_params).value();

Build performs any required training; Add appends vectors. BruteForce supports both:

auto base = vsag::Dataset::Make();
base->NumElements(num_vectors)
    ->Dim(dim)
    ->Ids(ids)
    ->Float32Vectors(datas)
    ->Owner(false);
index->Add(base);

Search

KnnSearch takes the query, k, and a JSON search-params string. BruteForce has no tunable search params, so an empty object is passed.

auto query = vsag::Dataset::Make();
query->NumElements(1)->Dim(dim)->Float32Vectors(query_vector)->Owner(false);

int64_t topk = 10;
auto result = index->KnnSearch(query, topk, R"({})").value();

for (int64_t i = 0; i < result->GetDim(); ++i) {
    std::cout << result->GetIds()[i] << ": " << result->GetDistances()[i] << std::endl;
}

The result contains up to k neighbors sorted by ascending distance to the query.

Threshold Filtering

Threshold filtering is supported by the maintained indexes: BruteForce, HGraph, IVF, Pyramid, SINDI, and SIMQ. HNSW and DiskANN are removed and unsupported; this option does not add or change behavior for either legacy index.

KNN search accepts an optional top-level threshold in the JSON search parameters:

{
  "threshold": 4.0,
  "hgraph": { "ef_search": 64 }
}

When present, the result contains at most k neighbors and every returned distance is less than or equal to threshold. The boundary is inclusive, results remain sorted by ascending distance, and fewer than k results—or no results—may be returned. When omitted, KNN behavior is unchanged. The value uses the index metric’s returned distance: squared L2 for l2, 1 - inner_product for ip, and 1 - cosine_similarity for cosine. Therefore negative thresholds can be meaningful for ip; the threshold must be a finite JSON number.

The same option is available through SearchRequest::threshold_ on BruteForce, HGraph, and IVF; Pyramid, SINDI, and SIMQ support the option through their KNN JSON parameters. These are the six maintained indexes supported by this feature. It only limits KNN results; use RangeSearch and its radius argument for range-search requests. Existing index-specific search parameters can be supplied alongside threshold.

Search Statistics

VSAG can return query-time statistics together with a search result. Statistics are useful for observability, debugging, and comparing search configurations.

Reading statistics

Dataset provides two views of the same result statistics:

• GetSearchMetrics() returns a typed snapshot. New C++ code should prefer this API.
• GetStatistics() returns the existing JSON representation for backward compatibility.
• GetStatistics(keys) returns selected JSON values. A missing key is returned as an empty string.

vsag::SearchRequest request;
request.query_ = query;
request.topk_ = 10;
request.params_str_ = R"({})";  // Statistics are enabled by default.

auto result = index->SearchWithRequest(request);
if (!result.has_value()) {
    // Handle result.error().
}

auto metrics = result.value()->GetSearchMetrics();
if (metrics.has_value()) {
    std::cout << metrics->distance_evaluations << std::endl;
    std::cout << metrics->DistanceEvaluations(
                     vsag::DistanceEvaluationPhase::APPROXIMATE)
              << std::endl;
}

// The compatible JSON view is still available.
std::cout << result.value()->GetStatistics() << std::endl;

The typed snapshot is the authoritative view when it is available. JSON is derived lazily from the snapshot and cached by the result dataset.

Enabling and disabling result statistics

Statistics are enabled by default. To disable them for one SearchWithRequest call, add the reserved framework key to the top level of params_str_:

request.params_str_ = R"({"want_statistics":false})";

When want_statistics is false:

• GetSearchMetrics() returns std::nullopt;
• GetStatistics() returns "{}";
• search results and distances are unchanged.

Disabling statistics is not a guarantee of lower latency: parsing/removing the explicit option and normalizing the request have a fixed cost, which can outweigh saved collection work for very small searches. Prefer typed reads over JSON when possible, and benchmark your workload.

BruteForce suppresses statistics collection when this parameter is false. Other indexes may still perform internal accounting, but they do not expose statistics in the result.

The legacy KnnSearch and RangeSearch overloads do not provide the per-request want_statistics suppression flag and preserve their existing JSON-statistics behavior. Indexes that support typed metrics may also attach a typed snapshot on these legacy paths; use SearchWithRequest when per-request suppression is required.

Typed-statistics support

Typed statistics are introduced incrementally. The current support matrix is:

Indexes without typed support continue to expose their existing JSON statistics when statistics are enabled.

Baseline fields

The baseline schema is owned by the search-statistics framework. Index-specific extensions must not overwrite these keys.

A value of zero is different from missing statistics. A collected empty search has a typed snapshot whose counters are zero. A search with statistics disabled has no typed snapshot.

Interpreting counters

• APPROXIMATE labels the main candidate-search phase, not distance accuracy. BruteForce’s exact FP32 scan is recorded in this phase; routing and rerank remain zero for this example.
• distance_evaluations counts recorded distance evaluations, not distinct candidates or returned neighbors. Evaluating a candidate again can add another evaluation. Phase and backend arrays partition the recorded evaluations along different axes; do not add the two arrays together.
• dist_cmp preserves the legacy index-specific comparison counter. It can differ from the new total and must not be treated as its alias across indexes or search paths.
• complete describes diagnostic distance accounting, not recall, search success, or timeout. The collector marks it false on an unknown backend or saturated distance accounting. A true value is not proof that every possible execution path is instrumented; consult the support matrix and inspect is_timeout independently.
• The collector’s 64-bit distance counters saturate at UINT64_MAX rather than wrapping, and mark accounting incomplete when an increment cannot be fully represented. Legacy 32-bit counters keep their existing update semantics; they do not gain a general saturation guarantee. Using an unsigned 64-bit JSON setter preserves their stored values but does not widen collection or recover overflow.

For a runnable example with runtime contract checks, see 330_feature_search_statistics.cpp.

Index-specific extensions

An index may add typed extension values using one of these types:

• uint32_t
• uint64_t
• bool
• double
• std::string

Extension availability depends on the index and search path. Applications read the const map returned by SearchResultMetrics::Extensions() and must check whether a key exists. Baseline names are reserved; only the internal collector can add extensions, and it rejects a colliding name.

Compatibility

• Existing GetStatistics() and GetStatistics(keys) APIs remain available.
• The default is to return statistics, preserving existing search behavior.
• A dataset without collected statistics continues to return "{}" from GetStatistics().
• Calling the legacy Statistics(string) setter clears any typed snapshot and makes the supplied JSON string authoritative.
• GetSearchMetrics() is a nonvirtual bridge and does not add a slot to the existing Dataset vtable.
• Per-request control uses the existing params_str_ member, so SearchRequest keeps its previous object layout for binary compatibility.

Maintenance contract

Changes to a search implementation must preserve these rules:

1. A typed snapshot is detached result data; live atomic counters must not escape the query. Snapshot creation happens after search workers complete. Counters are diagnostic values, not a transactional cross-counter view for concurrent writers.
2. JSON must be derived from typed metrics when a typed snapshot is attached.
3. Index extensions must not overwrite baseline fields.
4. Empty-result and early-return paths must honor the reserved want_statistics parameter.
5. A disabled result must be represented by std::nullopt and "{}", not by a collected all-zero snapshot.
6. Adding a baseline field, phase, backend, or extension type requires serializer, documentation, unit-test, and functional-test updates in the same change.
7. Adding typed support to an index requires updating the support matrix and running the public behavior contract in tests/test_search_statistics.cpp.

Run the focused tests with:

./build-release/tests/unittests "[search_metrics]"
./build-release/tests/functests "[search_statistics]"

C API

VSAG exports a C ABI in include/vsag/vsag_c_api.h. It wraps the same index implementations as the C++ API and is useful for language bindings and applications that need opaque handles and C-style functions.

The current installed header is not directly includable from a C translation unit: it contains an unguarded extern "C" block and uses C++ bool. Compile the translation unit that includes this header as C++ (for example, use a .cpp file). If the rest of the application is written in C, expose the required operations through a small application-owned C wrapper.

Lifecycle

Include the installed header from a C++ translation unit and link the normal VSAG library:

#include <vsag/vsag_c_api.h>

The basic lifecycle is:

1. Create an opaque vsag_index_t with vsag_index_factory.
2. Build or train/add vectors.
3. Search, update, serialize, or query the index.
4. Release the handle with vsag_index_destroy.

vsag_index_factory returns nullptr when creation fails. Other functions return Error_t; code == VSAG_SUCCESS indicates success and message contains error details otherwise.

const char* build_params =
    "{\"dtype\":\"float32\",\"metric_type\":\"l2\",\"dim\":128,"
    "\"index_param\":{\"base_quantization_type\":\"fp32\","
    "\"max_degree\":32,\"ef_construction\":200}}";

vsag_index_t index = vsag_index_factory("hgraph", build_params);
if (index == nullptr) {
    /* handle creation failure */
}

Error_t error = vsag_index_build(index, base, ids, 128, count);
if (error.code != VSAG_SUCCESS) {
    /* inspect error.message */
}

vsag_index_destroy(index);

Search result buffers

The caller owns the ids and dists buffers in SearchResult_t. Allocate at least k entries for both buffers before KNN or range search. VSAG writes no more than k results and stores the actual number in count.

int64_t result_ids[10];
float result_dists[10];
SearchResult_t result{};
result.dists = result_dists;
result.ids = result_ids;

Error_t error =
    vsag_index_knn_search(index, query, 128, 10, "{\"hgraph\":{\"ef_search\":100}}", &result);

The filter variants accept a FilterFunc_t. Returning true means the ID is valid and may be returned.

Range search result cap

Both C range-search functions require an explicit positive result cap:

Error_t
vsag_index_range_search(vsag_index_t index,
                        const float* query,
                        uint64_t dim,
                        float radius,
                        int64_t k,
                        const char* parameters,
                        SearchResult_t* result);

k must be at least 1. It is forwarded to the C++ range-search limited_size argument and also protects the caller-owned buffers: result.count never exceeds k. Applications upgrading from the older signature must add this argument to both vsag_index_range_search and vsag_index_range_search_with_filter.

API groups

• Create and destroy: vsag_index_factory, vsag_index_destroy.
• Populate: vsag_index_build, vsag_index_train, vsag_index_add.
• Search: vsag_index_knn_search, vsag_index_range_search, and their filter variants.
• Read and update: vsag_index_calculate_distance_by_ids, vsag_index_get_vector_by_ids, vsag_index_update_ids, vsag_index_update_vector, and vsag_index_update_vector_force.
• Copy and reuse: vsag_index_clone, vsag_index_export_model.
• Persistence: vsag_serialize_file, vsag_deserialize_file, vsag_serialize_write_func, and vsag_deserialize_read_func.

Support still depends on the selected index. An unsupported operation returns VSAG_UNSUPPORTED_INDEX_OPERATION.

Persistence errors

vsag_serialize_file and vsag_deserialize_file validate that the target file can be opened. Check the returned Error_t for VSAG_READ_ERROR, VSAG_MISSING_FILE, or another non-success code instead of assuming a file operation completed.

The callback-based persistence functions are available when the application manages its own storage. Their callback offsets and sizes use the OffsetType and SizeType aliases declared in the header.

Reference

include/vsag/vsag_c_api.h is the complete source-level reference for signatures, error codes, callbacks, and structures. Search parameters use the same JSON objects documented on the corresponding index pages.

pyvsag

pyvsag is the official Python binding for VSAG, implemented with pybind11. Sources live under python_bindings/ and python/.

Installation

pip install pyvsag

To build from source:

make pyvsag PY_VERSION=3.10
# Build wheels for multiple Python versions:
make pyvsag-all

Quick Start

pyvsag.Index(name, parameters) accepts the index name and a JSON-encoded parameter string, matching the C++ vsag::Factory::CreateIndex signature:

import json
import numpy as np
import pyvsag

dim = 128
num_elements = 10_000

data = np.random.random((num_elements, dim)).astype(np.float32)
ids = np.arange(num_elements, dtype=np.int64)

index_params = json.dumps({
    "dtype": "float32",
    "metric_type": "l2",
    "dim": dim,
    "index_param": {
        "base_quantization_type": "fp32",
        "max_degree": 32,
        "ef_construction": 300,
    },
})

index = pyvsag.Index("hgraph", index_params)
index.build(vectors=data, ids=ids, num_elements=num_elements, dim=dim)

query = np.random.random(dim).astype(np.float32)
search_params = json.dumps({"hgraph": {"ef_search": 60}})
result_ids, result_dists = index.knn_search(
    vector=query, k=10, parameters=search_params,
)
print(result_ids, result_dists)

Saving & Loading

index.save("index.bin")

new_index = pyvsag.Index("hgraph", index_params)
new_index.load("index.bin")

The current save and load wrappers do not propagate errors returned by the underlying serialization and deserialization operations. Verify that the output file was created and round-trip important indexes before relying on persisted data.

Index Operations

The Python binding exposes the following index-management methods in addition to build, search, save, and load:

# Add two dense vectors.
new_vectors = np.random.random((2, dim)).astype(np.float32)
new_ids = np.array([10_001, 10_002], dtype=np.int64)
index.add(new_vectors, new_ids, len(new_ids), dim)

assert index.check_id_exist(10_001)
print(index.get_num_elements(), index.get_memory_usage())
print(index.get_min_max_id())

# Calculate distances from one query to a candidate list.
candidate_ids = np.array([10_001, 10_002], dtype=np.int64)
distances = index.cal_distance_by_id(query, candidate_ids)

# Remove IDs; the return value is the number actually removed.
removed = index.remove(candidate_ids)

add accepts a flat contiguous array or a row-major two-dimensional matrix. For dtype: "float16", pass numpy.float16; for dtype: "bfloat16", pass a numpy.uint16 array containing BF16 bit patterns. Operation support remains index-dependent. Input validation and operations such as add and calc_distances_by_id raise Python exceptions, but remove, save, and load use the sentinel or unchecked behaviors described above instead of consistently propagating underlying operation failures.

Distance binding input safety

calc_distances_by_id and its legacy alias accept one 1D dense query whose length must equal the index dimension, plus a 1D ID array. Short, long, and empty queries are rejected by the C++ Dataset validation, not treated as missing IDs. NumPy inputs are converted to contiguous float32 / int64 arrays as needed, so positive- and negative-stride query and ID views retain their logical order. This does not add sparse, multi-vector, or multi-query support to the binding.

The Node.js equivalents calcDistancesById(query, ids) and legacy calDistanceById(query, ids) retain their 1D Float32Array result. They require exactly Float32Array queries and BigInt64Array IDs (other array kinds throw TypeError), validate the actual query length through the C++ Dataset API, and throw Error with the C++ message on operation failure. Missing IDs still produce -1; they are not operation failures.

Relationship with the C++ Library

pyvsag wraps the same vsag::Index API as C++ and shares the underlying index binaries. You can build an index in Python and load it in C++ (and vice versa) as long as parameters match.

More Examples

See examples/python/ in the repository.

Indexes

VSAG ships a family of index implementations that share a single builder-style API, one serialization format, and one set of operations (Build, Add, KnnSearch, RangeSearch, Remove, Serialize / Deserialize, …). They differ in the data structures and trade-offs they use under the hood.

The pages in this section cover the actively developed indexes:

brute_force is also available as an exact-search baseline (see Creating an Index and examples/cpp/105_index_brute_force.cpp).

Parameter conventions

All indexes share the same top-level build fields:

Index-specific build parameters live under the index_param sub-object; search-time parameters live under a sub-object named after the index (e.g. hgraph, ivf, sindi, sindi_v2, pyramid). LazyHGraph also uses the hgraph search object after it converts to graph phase. Concrete schemas are documented on each page and enumerated in Index Parameters.

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.

HGraph

HGraph is VSAG’s flagship graph-based index. It builds a hierarchical proximity graph and offers a rich set of quantization options, a unified build-parameter schema (index_param), and first-class support for reordering, incremental updates, deletion, and ELP-based runtime tuning.

For most dense-vector workloads (text / image / multimodal embeddings, 64–4096 dims, from a few thousand up to hundreds of millions of points), HGraph is the recommended default.

• Source: src/algorithm/hgraph.{h,cpp}
• Example: examples/cpp/103_index_hgraph.cpp

How it works

1. Graph construction. Vectors are organised in a layered proximity graph; upper layers act as navigation aids, the bottom layer connects every data point to its nearest neighbours within a max_degree budget. The construction algorithm can be NSW-style insertion (graph_type: "nsw", the default), ODescent (graph_type: "odescent"), or PiPNN (graph_type: "pipnn").
2. Quantization. The base storage is compressed with a configurable quantizer (base_quantization_type — fp32, fp16, bf16, sq8, sq8_local, sq4_local, sq4, sq8_uniform, sq4_uniform, pq, pqfs, rabitq, tq). Optionally, a second high-precision copy is kept (use_reorder: true with precise_quantization_type) and used to re-rank the candidates returned by the coarse search.
3. Search. Greedy beam search traverses the graph top-down, expanding the current frontier up to ef_search candidates. When reordering is enabled, the final list is re-scored against the precise representation.

Quick start

#include <vsag/vsag.h>

std::string params = R"({
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 128,
    "index_param": {
        "base_quantization_type": "sq8",
        "max_degree": 32,
        "ef_construction": 400
    }
})";
auto index = vsag::Factory::CreateIndex("hgraph", params).value();

// Build.
auto base = vsag::Dataset::Make();
base->NumElements(n)->Dim(128)->Ids(ids)->Float32Vectors(data)->Owner(false);
index->Build(base);

// Search.
auto query = vsag::Dataset::Make();
query->NumElements(1)->Dim(128)->Float32Vectors(q)->Owner(false);
auto result = index->KnnSearch(
    query, /*topk=*/10, R"({"hgraph": {"ef_search": 100}})").value();

Build parameters

Build-time parameters live under index_param. The table below highlights the keys most users need; the exhaustive list is in Index Parameters.

sq8_local and sq4_local support float32 L2/IP/cosine base and precise stores (including RaBitQ + local SQ4/SQ8 reranking). See layout, numeric limits and Tune compatibility.

use_reverse_edges is intended for workloads that need fast incoming-neighbor inspection, graph analysis, or future graph-maintenance algorithms. It is disabled by default because maintaining the reverse adjacency approximately doubles edge storage.

label_remap_type changes the internal label map, not user-visible IDs. "pg" is the default; "robin" selects the alternate robin-map implementation. Benchmark the target ID distribution before changing it.

PiPNN build boundary

Set graph_type: "pipnn" to use PiPNN for the initial, full Build. The PiPNN builder accepts dense float32 input with metric_type set to "l2", "ip", or "cosine". It builds the bottom graph from the original build vectors, then reuses HGraph’s route layers, storage, search, filtering, reordering, incremental Add, removal, and serialization paths. The persistent base storage may use a supported quantizer such as sq8, including RaBitQ with SQ8 reorder. Cache-assisted build and deduplicated vector storage are not supported with PiPNN. The pipnn_* parameters in the table above tune this builder; ef_construction does not. The existing alpha parameter controls PiPNN’s final robust pruning.

build_thread_count parallelizes vector preparation, partitioning, candidate generation, and final pruning. Keep OPENBLAS_NUM_THREADS=1 when benchmarking so BLAS threads do not obscure builder scaling. The reproducible tools/eval/pipnn_parallel.yaml workload compares NSW, ODescent, and PiPNN at a matched Recall@10 target on SIFT1M and query-validates every graph.

Deduplicating vector storage

Set both support_duplicate: true and deduplicate_storage: true to let duplicate vectors share one physical code slot while retaining their individual labels. This option currently supports only dense-vector HGraph indexes using graph_type: "nsw"; it is not available for graph_type: "odescent" or graph_type: "pipnn".

The following operations and configurations are not supported while storage deduplication is enabled:

• force removal (support_force_remove: true);
• cache-assisted build after ImportCache();
• Merge;
• legacy v0.14 serialization.

UpdateVector is supported only for IDs whose vector storage is not shared with another duplicate-group member.

Current serialization and streaming serialization are supported.

Supported input data types

The dtype field in the top-level build config selects how Dataset interprets the raw vector bytes. HGraph supports four input types; the dtype value, the corresponding Dataset setter, and the example demonstrating each combination are summarised below.

The dim value is the logical vector dimensionality (number of elements), not the byte length, so the same dim is reused across all four data types.

int8 input

Quantized int8 vectors are passed directly via Int8Vectors:

std::vector<int8_t> data(num_vectors * dim);  // populate with int8 elements
auto base = vsag::Dataset::Make();
base->NumElements(num_vectors)->Dim(dim)->Ids(ids)
    ->Int8Vectors(data.data())->Owner(false);

Build config (note dtype: "int8"):

{
    "dtype": "int8",
    "metric_type": "l2",
    "dim": 128,
    "index_param": {
        "base_quantization_type": "pq",
        "max_degree": 26,
        "ef_construction": 100,
        "alpha": 1.2
    }
}

Queries use the same Int8Vectors setter and the same dtype. A runnable example is 316_index_int8_hgraph.cpp.

float16 / bfloat16 input

FP16 and BF16 vectors are both passed through Float16Vectors, which takes a const uint16_t* that points at the 16-bit storage of each element. Conversion from float is up to the caller; inside the VSAG source tree there are convenience helpers (vsag::generic::FloatToFP16 in src/simd/fp16_simd.h and vsag::generic::FloatToBF16 in src/simd/bf16_simd.h), but these are internal headers that are not installed under include/vsag/. Application code linking against an installed VSAG library should provide its own conversion (for example, copy the small helper, use _cvtss_sh / F16C intrinsics, or any FP16 library of choice). The snippet below uses the in-tree helper for brevity:

// The fp16/bf16 helpers below live in src/simd/ and are not part of the public
// installed headers. Replace with your own float -> uint16_t conversion when
// linking against an installed VSAG.
#include "simd/fp16_simd.h"  // FloatToFP16 (for BF16, use simd/bf16_simd.h / FloatToBF16)

std::vector<uint16_t> data(num_vectors * dim);
for (size_t i = 0; i < data.size(); ++i) {
    data[i] = vsag::generic::FloatToFP16(some_float_source());
}
auto base = vsag::Dataset::Make();
base->NumElements(num_vectors)->Dim(dim)->Ids(ids)
    ->Float16Vectors(data.data())->Owner(false);

Build config:

{
    "dtype": "float16",
    "metric_type": "l2",
    "dim": 128,
    "index_param": {
        "base_quantization_type": "pq",
        "max_degree": 26,
        "ef_construction": 100,
        "alpha": 1.2
    }
}

To switch the example to BF16, change dtype to "bfloat16" and replace FloatToFP16 with FloatToBF16; the Float16Vectors setter and the rest of the build/search flow stay the same. A runnable FP16 example is 321_index_fp16_hgraph.cpp.

Note. The header comment at the top of 321_index_fp16_hgraph.cpp currently mentions a BFloat16Vectors() setter, but no such setter exists — Float16Vectors is the single entry point for both FP16 and BF16. Use it for both dtype: "float16" and dtype: "bfloat16".

Choosing an input type

• Pick float32 when accuracy matters most and memory budget allows; this is the default.
• Pick float16 / bfloat16 to halve the input storage. FP16 has a smaller exponent range; BF16 has fewer mantissa bits but the same exponent range as FP32, which is often preferable for embedding-style vectors.
• Pick int8 when your data is already integer-quantised (e.g. produced by an upstream quantiser or by a model with int8 outputs). With int8 input you typically still combine a coarse quantizer such as pq / sq8 for the in-index storage.

The chosen dtype only constrains the input representation. The on-disk / in-memory storage is still controlled by base_quantization_type (and optionally precise_quantization_type when use_reorder: true), so e.g. dtype: "float16" + base_quantization_type: "sq8" is valid.

Search parameters

Search-time parameters live under the hgraph sub-object:

auto result = index->KnnSearch(
    query, topk, R"({"hgraph": {"ef_search": 200}})").value();

Brute-force fallback under highly selective filters (brute_force_threshold)

Graph traversal is the right strategy when most candidates pass the filter — the graph quickly reaches the neighborhood of the query. As filter selectivity increases (only a tiny fraction of vectors survive), the beam has to expand far more nodes just to fill ef_search with valid candidates, and recall drops. At some point an exhaustive scan over the surviving ids is both faster and exact.

brute_force_threshold lets HGraph make that switch automatically on a per-query basis:

// When the active filter keeps ≤ 1% of ids, run an exact scan instead.
auto params = R"({"hgraph": {"ef_search": 200, "brute_force_threshold": 0.01}})";
auto result = index->KnnSearch(query, topk, params, my_filter).value();

How it works (src/algorithm/hgraph/hgraph_search.cpp):

• The fallback only fires when all of the following hold:
  • brute_force_threshold > 0.0, and
  • a filter is supplied, and
  • filter->ValidRatio() <= brute_force_threshold.
• The accuracy of Filter::ValidRatio() matters — it is the user-supplied hint the dispatcher checks against the threshold. See Filtered Search for the API contract.
• The scan iterates every valid inner id and computes distances in batches of 64 using the most precise flatten storage available (raw vectors if store_raw_vector was set, otherwise the high-precision reorder codes when use_reorder=true, otherwise the base quantized codes).
• Because the scan already uses precise codes when present, the post-search reorder pass is skipped for queries that took the brute-force branch.
• Applies to KnnSearch (the non-iterator overload, which is what SearchWithRequest and the standard KnnSearch(query, k, params, filter) call) and to RangeSearch. It does not apply to the iterator-style KnnSearch(..., IteratorContext*&, ...), because a single sweep cannot be paged across multiple iterator calls.

Picking a value:

• Leave at 0.0 (default) for unfiltered or weakly filtered workloads.
• For highly selective filters, 0.01–0.05 is a reasonable starting point. Setting it higher than that effectively turns the index into a brute-force scanner whenever a filter is present.
• The cost of the brute-force scan is roughly O(N × dim) where N is the total number of indexed vectors (regardless of selectivity, because every id is visited to check CheckValid). The benefit grows when graph search would otherwise need a much larger ef_search to recover recall.

See 322_feature_hgraph_brute_force_threshold.cpp for a runnable brute-force fallback example.

Filter Skip Strategy (skip_ratio and skip_strategy)

When searching with a filter, HGraph needs to frequently call Filter::CheckValid() during graph traversal to verify whether each candidate point is valid. This check can be expensive (especially for complex filter logic). skip_ratio and skip_strategy provide a probabilistic optimization: they skip some filter checks to speed up the search, but may reduce recall.

How It Works

This is a probabilistic optimization strategy: we don’t know in advance which points are valid, so we decide probabilistically whether to visit each point.

• skip_ratio (default 0.2): Controls the aggressiveness of skipping filter checks. skip_ratio=0.2 means skip 20% of candidate checks and only check 80%. Higher values skip more, making search faster but potentially reducing recall.
• skip_strategy (default “deterministic_accumulative”): Determines how skipping is distributed:
  • “random”: Random skipping. Each point is visited independently with probability visit_ratio = valid_ratio + (1 - valid_ratio) * (1 - skip_ratio), so roughly a 1 - skip_ratio fraction of invalid points are skipped.
  • “deterministic_accumulative”: Deterministic cumulative skipping. Emits visit decisions at fixed intervals so that the long-run visit ratio matches the target visit_ratio, with lower variance than the random strategy.

The specific formula:

• Let valid_ratio be the filter’s global validity rate (from Filter::ValidRatio())
• Probability of visiting each point = valid_ratio + (1 - valid_ratio) * (1 - skip_ratio)
• In expectation, this targets skipping about skip_ratio of invalid candidate checks when Filter::ValidRatio() is accurate

Usage Examples

// Conservative setting: skip 10% of invalid candidate checks, suitable for high-recall
// scenarios where latency is less critical
auto params = R"({"hgraph": {"ef_search": 200, "skip_ratio": 0.1}})";
auto result = index->KnnSearch(query, topk, params, my_filter).value();

// Use random strategy
auto params = R"({"hgraph": {"ef_search": 200, "skip_ratio": 0.2, "skip_strategy": "random"}})";
auto result = index->KnnSearch(query, topk, params, my_filter).value();

// Aggressive skipping: skip 50% of invalid candidate checks for lower latency
auto params = R"({"hgraph": {"ef_search": 200, "skip_ratio": 0.5}})";
auto result = index->KnnSearch(query, topk, params, my_filter).value();

Choosing Values

• Default 0.2: Suitable for most scenarios, balancing performance and recall.
• 0.1 or lower: Conservative setting, suitable for scenarios with high recall requirements where latency is less critical.
• 0.5 or higher: Aggressive skipping, suitable for latency-sensitive scenarios where recall degradation is acceptable (e.g., real-time recommendation systems).
• 0.0: Don’t skip any points, equivalent to disabling this optimization (all points will be checked).

Important notes:

• Only applies to searches with filters. These parameters are ignored when no filter is present.
• Performance optimization works better when Filter::ValidRatio() is accurately estimated.
• Can be used together with brute_force_threshold: when the filter is very strict (ValidRatio is very small), brute_force_threshold will trigger brute-force fallback; otherwise, graph traversal + skip optimization is used.

When to use HGraph

• Dense float vectors with dimensions roughly between 64 and 4096.
• Latency-sensitive queries where high recall matters.
• Mixed workloads with incremental insertion (optionally force removal via support_force_remove).
• Memory-constrained deployments that benefit from sq8 / sq4_uniform / pq — often in combination with use_reorder to recover recall.

For repeated daily or snapshot builds with stable source identifiers, see HGraph Build Cache. It documents Dataset::SourceID, ExportCache/ImportCache, persist_source_id, and cache hit-rate diagnostics.

If your workload is partition-heavy (coarse-grained buckets scanned per query) or strongly I/O-bound on a SSD, compare against IVF before committing to HGraph.

See also

• Creating an Index
• Graph Enhancement
• Optimizer (Tune)
• Serialization

LazyHGraph

LazyHGraph is an adaptive dense-vector index that starts as an exact BruteForce index and automatically converts to HGraph after the collection reaches a configurable transition_threshold. It is useful when a dataset starts small but is expected to grow: early searches stay exact and avoid graph build overhead, while larger collections get HGraph’s approximate-search latency and quantization options.

• Source: src/algorithm/lazy_hgraph.{h,cpp}
• Example: examples/cpp/111_index_lazy_hgraph.cpp

How it works

1. Flat phase. Before the threshold is reached, data is stored in an internal BruteForce index using FP32 vectors. Search is exact.
2. Transition. When Build receives at least transition_threshold vectors, or Add grows the flat phase to that size, LazyHGraph builds an internal HGraph from the flat data.
3. Graph phase. After transition, new data and search requests are handled by the internal HGraph. Search parameters keep using the hgraph search object.

Quick start

#include <vsag/vsag.h>

std::string params = R"({
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 128,
    "lazy_hgraph": {
        "transition_threshold": 1000,
        "hgraph": {
            "base_quantization_type": "sq8",
            "max_degree": 26,
            "ef_construction": 100,
            "build_thread_count": 4
        }
    }
})";
auto index = vsag::Factory::CreateIndex("lazy_hgraph", params).value();

auto base = vsag::Dataset::Make();
base->NumElements(n)->Dim(128)->Ids(ids)->Float32Vectors(data)->Owner(false);
index->Add(base);

auto query = vsag::Dataset::Make();
query->NumElements(1)->Dim(128)->Float32Vectors(q)->Owner(false);
auto result = index->KnnSearch(
    query, /*topk=*/10, R"({"hgraph": {"ef_search": 100}})").value();

Build parameters

LazyHGraph accepts its build parameters in a top-level lazy_hgraph object. For compatibility with the generic factory shape, the same object may also be provided as index_param.

LazyHGraph only supports top-level dtype: "float32". The flat phase is fixed to FP32 BruteForce storage and does not accept separate flat quantization parameters.

Search parameters

Search parameters use the same hgraph object as HGraph:

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

In the flat phase, search is exact. In the graph phase, the internal HGraph uses the supplied HGraph search parameters such as ef_search.

Lifecycle notes

• Build chooses the initial phase from the input size: below transition_threshold stays flat; at or above the threshold builds HGraph directly.
• Add can trigger the one-way transition from flat to graph.
• Flat-phase Remove always performs physical removal, even if the caller passes RemoveMode::MARK_REMOVE, so graph transition does not carry tombstones.
• GetExtraInfoByIds, UpdateExtraInfo, and extra-info filtering are supported in both phases. See Extra Info.

When to use LazyHGraph

• A dense FP32 collection starts small and grows over time.
• Exact results are preferred while the collection is small.
• The same index should automatically switch to HGraph once approximate graph search becomes worthwhile.

Use HGraph directly when the dataset is already large at build time, when you need non-FP32 input types, or when you want graph behavior from the first insertion.

See also

• HGraph
• Extra Info
• Creating an Index

IVF

IVF (Inverted File) is VSAG’s partition-based index. It clusters the corpus into buckets at build time, and at query time only scans the buckets whose centroids are closest to the query. This turns an O(N) linear scan into O(N · scan_buckets_count / buckets_count) with tunable recall/latency.

IVF trades a little recall (compared to graph indexes) for lower memory overhead, higher throughput on batch workloads, and simpler sharding — which makes it a good default when the corpus is large (hundreds of millions or more), when memory is tight, or when queries are naturally parallelizable.

• Source: src/algorithm/ivf.{h,cpp}, src/algorithm/ivf_parameter.{h,cpp}
• Example: examples/cpp/106_index_ivf.cpp

How it works

1. Clustering. A sample of the dataset is clustered with k-means (or sampled randomly, ivf_train_type: "random") to produce buckets_count centroids.
2. Assignment. Every vector is written to the inverted list of its nearest centroid, stored in the configured coarse quantization (base_quantization_type). Optionally, a second high-precision copy is kept (use_reorder: true) for post-filter reordering.
3. Search. For each query, the scan_buckets_count nearest centroids are computed first, then the vectors in those buckets are scored. When reordering is enabled, factor controls how many extra candidates are fetched from the coarse stage before being re-scored with the precise quantizer.

A second partition strategy, GNO-IMI (partition_strategy_type: "gno_imi"), splits the space into two orthogonal sets of centroids (first_order_buckets_count × second_order_buckets_count) for even finer partitioning on very large corpora.

Quick start

#include <vsag/vsag.h>

std::string params = R"({
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 128,
    "index_param": {
        "buckets_count": 256,
        "base_quantization_type": "sq8",
        "partition_strategy_type": "ivf",
        "ivf_train_type": "kmeans"
    }
})";
auto index = vsag::Factory::CreateIndex("ivf", params).value();

// Build.
auto base = vsag::Dataset::Make();
base->NumElements(n)->Dim(128)->Ids(ids)->Float32Vectors(data)->Owner(false);
index->Build(base);

// Search.
auto query = vsag::Dataset::Make();
query->NumElements(1)->Dim(128)->Float32Vectors(q)->Owner(false);
auto result = index->KnnSearch(
    query, /*topk=*/10,
    R"({"ivf": {"scan_buckets_count": 16}})").value();

Input data type

The public Build, Add, and search paths currently accept FP32 vectors supplied with Dataset::Float32Vectors; set dtype to "float32". base_quantization_type selects internal encoding and storage and does not enable FP16/BF16 input. dtype: "int8" is not supported when creating an IVF index.

Build parameters

Build-time parameters live under index_param. See Index Parameters for the exhaustive list.

precise_codes_layout: "bucket" requires use_reorder: true. It supports memory_io, block_memory_io, buffer_io, async_io, and uring_io (when io_uring is available). mmap_io and pqfs precise quantization are not supported. The bucket layout currently requires buckets_per_data: 1; configurations that assign one vector to multiple buckets are rejected.

For both flat and bucket layouts, serialized precise codes can be loaded read-only from an external Reader. Pass precise_io_type: "reader_io" and precise_reader to Index::Load. The reader must expose exactly the high_precision_codes block payload for flat, or the ivf_precise_bucket block payload for bucket. reader_io uses the normal read cache when precise_enable_read_cache is enabled.

vsag::LoadParameters load_parameters;
load_parameters.Set("precise_io_type", "reader_io")
    .Set("precise_enable_read_cache", true)
    .Set("precise_cache_total_size", 256ULL * 1024 * 1024)
    .SetReader("precise_reader", precise_codes_reader);
auto loaded = vsag::Index::Load(stream, load_parameters).value();

reader_io is a load-and-query placement policy. Build the index with a writable precise IO, serialize it, and then use the external reader when loading it for search.

A rule of thumb for buckets_count is sqrt(N) to 4 * sqrt(N) where N is the corpus size.

GPU-accelerated build

Building an IVF index is dominated by two things: clustering the training sample into centroids, and then assigning every base vector to its bucket. Clustering grows with buckets_count, because the sample does too (train_sample_count defaults to max(65536, 64 * buckets_count)), and with ivf_train_type: "kmeans" the seeding pass alone is O(buckets_count * train_sample_count * dim) and runs single-threaded.

When VSAG is built with ENABLE_CUDA=ON, both move to a CUDA device. Set enable_gpu_build to turn it on:

{
    "buckets_count": 4096,
    "base_quantization_type": "fp32",
    "partition_strategy_type": "ivf",
    "ivf_train_type": "kmeans",
    "enable_gpu_build": true,
    "gpu_device_id": 0
}

Four passes run on the device: k-means++ seeding, nearest-centroid assignment and centroid accumulation inside clustering, and the bucket assignment of the base vectors afterwards. ivf_train_type: "random" does not cluster, so only the last one applies to it.

The four settings reach the ivf partition strategy only. With partition_strategy_type: "gno_imi" they are accepted and ignored, as the other strategy-specific parameters in the table are, and that build stays on the host.

Scope. Only the build changes. Search is untouched: queries still route through the graph, which is the right shape for one query at a time. The four settings are recorded in the index footer as every other build parameter is, so two otherwise identical builds are not byte-identical, but the compatibility check on load ignores them: an index built with the backend on loads into a reader configured any other way, including one on a machine with no GPU, and then behaves as that reader is configured. The centroids can differ slightly from a host build’s: the random choices come from the caller’s generator either way, but the device sums each cluster with atomics in no fixed order.

Fallback. A pass that declines is taken by the host, silently, and returns what a build with the backend off would have returned. This happens when VSAG was built without CUDA, no device is present, gpu_device_id names an ordinal the machine does not have, the problem is below gpu_min_work_threshold, the budget cannot hold what a pass needs, or any CUDA call fails. A build never fails because of the backend.

Two cases stay on the host by design. Inner-product metrics order buckets by the dot product alone, which is not what the device pass minimises, so they keep the graph routing. A build that asked for a reproducible reduction keeps centroid accumulation on the host as well, since the device sums with atomics whose order is not fixed.

Memory. Vectors are streamed in chunks, so the corpus does not have to fit in device memory; only the centroids and one chunk do. The working set is bounded by gpu_memory_budget, by default derived from what the device reports free, so the same build behaves on a small card and makes use of a large one. Seeding differs only in shape: it sweeps the whole training sample once per centroid, so the sample has to be resident rather than chunked, and a sample the budget cannot hold sends seeding back to the host while the other passes stay on it. When no budget is named the chunked passes take a default ceiling, since a chunk larger than what saturates the device only costs more; seeding takes what the device has free, because a ceiling there would only push large samples to the host.

Measured on SIFT1M (1M base vectors, 128 dimensions), against a 48-thread host build as the baseline:

The speedup grows with buckets_count because clustering takes a larger share of the build. How large it is depends on the balance between the host’s CPU and its GPU, which is also what gpu_min_work_threshold exists to retune.

Recall moves because the device compares against every centroid where the host does not, in two places.

Assigning base vectors to buckets, on the default use_route_graph: true layout, searches the routing graph, which is approximate. On 20000 random vectors of 64 dimensions the two paths agreed exactly at buckets_count 16; at 256 and 1000 they placed roughly 10% and 12% of the vectors in different buckets, the device naming the nearer centroid in every one of those cases, and the mean distance to the assigned centroid improved by under 1% and by about 2%. The figures shift a little from run to run, because training is not seeded and each run clusters differently; they held across unit-norm and raw random data. The scan layout assigns exactly on either path and does not move.

Clustering does the same above 10000 centroids, where the host switches to a graph search over the centroids to keep training affordable.

So a build with the backend on assigns somewhat better, not only faster. The evidence for that is the distance comparison above, not the recall column: the table is one run per configuration, and recall between two separately trained indexes moves by more than the differences it shows. Four builds with identical settings on 50000 random vectors of 128 dimensions spanned a full point of recall, against the hundredths of a point in the table. Read that column as showing no regression, not as measuring the gain. Below those sizes the two agree except where two centroids are equidistant from a point to within floating-point rounding.

RaBitQ split storage

Set both quantizers to rabitq and divide the stored precision into filter (x) and supplement (y) bits:

{
    "base_quantization_type": "rabitq",
    "precise_quantization_type": "rabitq",
    "rabitq_bits_per_dim_query": 32,
    "rabitq_bits_per_dim_base": 3,
    "rabitq_bits_per_dim_precise": 5,
    "use_reorder": true
}

IVF stores the x-bit filter planes in bucket-local 32-vector packed blocks and stores the y-bit supplement separately. The default candidate_reorder strategy scans only the packed x bits, retains factor * topk candidates, and carries the byte-LUT-quantized x-bit inner product together with each candidate’s source bucket, offset, and version. Normal reranking combines this saved inner product with the y-bit supplement contribution. It does not reread or unpack x-bit planes and does not reconstruct the inner product from a distance hint.

For residual L2 candidate search, all routed buckets share one LUT built from the original transformed query. Per-lane factors recover the raw filter-code contribution and combine it with the supplement under the original query, so normal reranking does not build a q-c computer. A correctness fallback may unpack x bits only when the saved value or factors are invalid, source provenance is stale, or a FastScan lane could not produce a valid result.

The split configuration requires x >= 1, y >= 1, x + y <= 8, rabitq_bits_per_dim_query: 32, use_reorder: true, and buckets_per_data: 1. Bucket-local graphs (graph_build_threshold > 0) are not supported with split storage. Supported homogeneous IO backends are memory_io, block_memory_io, buffer_io, async_io, mmap_io, and reader_io; the supported hybrid layout is filter block_memory_io plus supplement async_io.

Search parameters

Search-time parameters live under the ivf sub-object:

auto result = index->KnnSearch(
    query, topk,
    R"({"ivf": {"scan_buckets_count": 32, "factor": 2.0, "parallelism": 4}})").value();

auto fast_result = index->KnnSearch(
    query, topk,
    R"({"ivf": {"scan_buckets_count": 32, "factor": 2.0, "enable_reorder": false}})").value();

When to use IVF

• Large corpora (hundreds of millions of vectors and above), especially when the working set does not fit comfortably in RAM.
• Batch or high-throughput workloads where per-query latency is less critical than queries-per-second.
• Memory-tight deployments that benefit from aggressive quantization (sq8, sq4_uniform, pq, pqfs) combined with use_reorder to recover recall.
• Shard-friendly setups: buckets map naturally onto shards or disk blocks.

For latency-sensitive, high-recall workloads on dense embeddings, compare against HGraph first.

See also

• Creating an Index
• Index Parameters
• Serialization

SINDI

SINDI (Sparse INverted Dense Index) is VSAG’s index for sparse vectors — the kind produced by BM25, SPLADE, and other learned-sparse encoders. Unlike the dense indexes (HGraph, IVF), SINDI operates directly on term/value pairs and is one of the VSAG indexes that accepts dtype: "sparse".

• Source: src/algorithm/sindi/
• Example: examples/cpp/109_index_sindi.cpp

How it works

1. Window-based inverted lists. Documents are grouped into fixed-size windows (window_size). Within each window, an inverted list per term maps a term id to the (doc_id, value) pairs that mention it.
2. Optional pruning and quantization. During construction, doc_prune_ratio drops low-weight terms per document. use_quantization: true stores SQ8 values, while use_quantization: "fp16" stores half-precision values.
3. Scoring. At query time, SINDI iterates the non-zero terms of the query, walks the corresponding inverted lists in each window, aggregates contributions into a max-heap of size n_candidate, and returns the top-k. When use_reorder is enabled, the candidates are re-scored against a forward store. The default forward store keeps FP32 values. rerank_type: "fp16" stores half-precision values and converts them to FP32 for scoring, while rerank_type: "dmq8" uses a compressed DMQ store to reduce rerank memory further.

Distance is returned as 1 - inner_product so results sort ascending as in the dense indexes.

For deployments that need both in-memory and disk-based I/O, use SINDI_V2.

Quick start

#include <vsag/vsag.h>

std::string params = R"({
    "dtype": "sparse",
    "metric_type": "ip",
    "dim": 1024,
    "index_param": {
        "term_id_limit": 30000,
        "window_size": 50000,
        "doc_prune_ratio": 0.0,
        "use_quantization": false,
        "use_reorder": false,
        "remap_term_ids": false
    }
})";
auto index = vsag::Factory::CreateIndex("sindi", params).value();

// Build a dataset of SparseVector.
auto base = vsag::Dataset::Make();
base->NumElements(n)
    ->SparseVectors(sparse_vectors)  // vsag::SparseVector*
    ->Ids(ids)
    ->Owner(false);
index->Build(base);

// Search.
auto query = vsag::Dataset::Make();
query->NumElements(1)->SparseVectors(&query_vec)->Owner(false);
auto result = index->KnnSearch(
    query, /*topk=*/10,
    R"({"sindi": {"n_candidate": 100}})").value();

Build parameters

Build-time parameters live under index_param. dtype must be "sparse" and metric_type must be "ip".

dim vs term_id_limit. For the sparse vector {0:0.1, 2:0.5, 177:0.8}, dim is 3 (three non-zero entries) while term_id_limit must be ≥ 178 (largest term id + 1). Sizing term_id_limit to your vocabulary is the most common first-time mistake.

Sparse value formats

use_quantization retains its legacy boolean behavior and also accepts one string value:

Indexes built with false or true retain the legacy serialization representation. Older VSAG versions cannot parse a SINDI index that uses the new "fp16" value format; upgrade readers before deploying FP16 artifacts.

Rerank value formats

rerank_type controls the separate forward store created by use_reorder: true; it is independent of the posting-list use_quantization setting. fp16 keeps query values and accumulation in FP32 but stores document values in FP16. Because term IDs remain 32-bit, the core bytes per non-zero forward-store entry decrease from 8 to 6 before record and block overhead. FP16 conversion adds compute work, so latency may improve for memory-bound workloads but can regress for short or cache-resident vectors. Measure with representative data.

Both fp16 and dmq8 require use_reorder: true. Older VSAG versions cannot read the FP16 rerank payload.

Immutable low-memory build

Set immutable: true when the completed SINDI index is read-only:

{
    "dtype": "sparse",
    "metric_type": "ip",
    "dim": 1024,
    "index_param": {
        "term_id_limit": 30000,
        "window_size": 50000,
        "use_quantization": "fp16",
        "remap_term_ids": true,
        "immutable": true
    }
}

During Build(), each completed mutable window is compacted into an immutable payload and the temporary window is released before construction continues. In the Sparse4M FP16 measurement reported with this feature, peak build memory fell from 27.03 GB to 6.08 GB (77.51% lower), while build time increased from about 330 seconds to 599 seconds. Treat these figures as workload-specific evidence, not a capacity guarantee.

The immutable runtime supports KNN and range search plus legacy Serialize/Deserialize. It rejects incremental Add and GetSparseVectorByInnerId. Single-ID CalcDistanceById and batch CalcDistancesById (including the legacy CalDistanceById alias) are supported; see distance-by-ID. Mutable and immutable runtimes both support SerializeStreaming, DeserializeStreaming, and Index::Load. The serialized index must be loaded into a SINDI created with the same immutable setting. New indexes record the sorted posting-list format version and skip normalization when loaded. Indexes written without this marker remain compatible and are normalized during loading.

Host filtering

Mutable and immutable SINDI and SINDI_V2 indexes can group documents by their source host and avoid returning documents from other hosts. Attach a complete string host array to a host-aware Build() or mutable Add() batch. Use an empty string for a document with no host:

base->NumElements(n)
    ->SparseVectors(sparse_vectors)
    ->Ids(ids)
    ->StringMetadata("host", base_hosts)
    ->Owner(false);
index->Build(base);

std::string query_host = "example.com";
query->NumElements(1)
    ->SparseVectors(&query_vec)
    ->StringMetadata("host", &query_host)
    ->Owner(false);

Each Build() or mutable Add() batch groups internal IDs by host while preserving external labels. Host queries scan the relevant posting windows and apply exact membership checks over the host’s one or more internal-ID ranges. Repeated mutable Add() calls may append disjoint ranges for the same host. Tombstones and an additional user Filter are applied together with host membership.

Host strings are matched byte for byte without case folding or URL normalization. VSAG assigns compact internal IDs and persists the string-to-ID dictionary with the index; callers never provide those IDs. The empty string is the missing-host bucket. Once a mutable index contains host metadata, every later Add() must provide a complete host array; host metadata cannot be introduced after host-unaware documents. An empty-string query searches only missing-host documents, while omitting host preserves full-index KNN behavior. An unknown host returns an empty result. Indexes built without base host metadata ignore query host metadata and retain their previous behavior. The old numeric host_id input is rejected. Host filtering currently applies only to KNN; range search keeps its existing full-index behavior.

Publish-time filtering

Mutable and immutable SINDI can filter KNN queries by a document publication timestamp, with or without reranking. Supply one Unix timestamp in seconds per base document through int64 metadata. 0 means that the document has no publication time:

int64_t base_times[] = {0, 1777593600, 1777680000};
base->Int64Metadata("publish_time_stamp", base_times);

int64_t query_time = 1777593600;
query->Int64Metadata("publish_time_stamp", &query_time)->Owner(false);

int64_t time_begin = 1777593600;
int64_t time_end = 1777766399;
query->Int64Metadata("publish_time_stamp_begin", &time_begin)
    ->Int64Metadata("publish_time_stamp_end", &time_end)
    ->Owner(false);

SINDI normalizes every positive timestamp to a UTC epoch day with timestamp / 86400. A single timestamp matches every document on the same UTC day. A range is inclusive after both endpoints are normalized to UTC days. The two range endpoints must be supplied together, must satisfy begin <= end, and cannot be combined with the single-value selector. Query values must be positive. Base values must be non-negative; negative values are rejected. Timestamps whose epoch day exceeds INT32_MAX are rejected.

Documents with base value 0 remain searchable when a query omits time selectors, including host-only queries, but never match a time query. Every base document still needs one array entry. An index built without publish_time_stamp rejects a query that supplies any time selector.

A time-aware build orders documents by publication timestamp, cuts the ordered sequence into logical partitions of window_size documents, and groups by host inside each partition. Missing times form one final partition. Search first selects partitions whose UTC-day range intersects the query, then applies exact per-document day and optional host checks before candidates enter the heap. Time, host, tombstone, and user Filter conditions use AND semantics. Failed or skipped documents can make adjacent logical partitions share a physical window; the exact day check keeps boundary results correct.

Time-aware indexes are build-once. A mutable index may receive publish_time_stamp through Build() or the first Add() while empty, but rejects every later Add(). Mutable host-only indexes retain incremental Add() support. Publish-time filtering supports mutable and immutable indexes with either use_reorder setting, applies only to KNN search, and is preserved by standard and streaming serialization. A restored mutable time-aware index remains build-once.

Queries without a time selector scan every time and missing-time partition. Host-only queries select that host from every partition. Exact time filtering disables term-level posting pruning in each selected window, so time queries may scan more postings than host-only queries; wider ranges also select more windows. A host-only query on a time-enabled index can require a full scan for windows that cross partition or host boundaries.

Search parameters

Search-time parameters live under the sindi sub-object:

After combining the ratio and threshold limits, SINDI scans at least one posting from every non-empty term list.

Within each window, postings for a term are sorted by their stored value in descending order, then by internal document id in ascending order. If both term-prune limits are enabled, the scanned prefix is the smaller of floor(list_size · (1 - ratio)) and floor(threshold / window_count). SINDI chooses the heap-insertion strategy automatically from the build-time doc_prune_ratio and search-time query_prune_ratio. With the current 0.1 threshold, SINDI uses the distance-array insertion path when both ratios are <= 0.1; if either ratio is greater than 0.1, it uses term-list heap insertion. The legacy use_term_lists_heap_insert search parameter is ignored; configure pruning ratios instead.

auto result = index->KnnSearch(
    query, topk,
    R"({"sindi": {"n_candidate": 200, "filter_callback_limit": 10000, "query_prune_ratio": 0.1}})").value();

When to use SINDI

• Sparse retrieval with BM25, SPLADE, uniCOIL, or similar learned-sparse encoders.
• Hybrid dense+sparse pipelines where SINDI handles the sparse leg in parallel with HGraph / IVF for dense embeddings.
• Memory-constrained deployments of sparse corpora (use_quantization: true selects SQ8, while "fp16" halves FP32 posting value bytes; use_reorder: true trades forward-store memory for recall, rerank_type: "fp16" reduces forward-store value bytes with modest precision loss, and rerank_type: "dmq8" compresses that store further).
• Read-only snapshots that need lower peak build memory (immutable: true), accepting slower construction and no incremental writes.

SINDI does not accept dense vectors and supports only inner-product similarity. Range search and id-based filtering are supported; see the example for usage. When rerank_type is dmq8, codebooks are fixed by the initial build, so incremental Add after the model is established and UpdateVector are not supported.

Practical guidance

• For Chinese corpora, we recommend encoding sparse vectors with BGE-M3. For English corpora, SPLADE is the more common default.
• BGE-M3 can emit both sparse and dense vectors. Today SINDI handles the sparse leg, and VSAG plans to support fused sparse+dense scoring in a future release.
• Sparse vectors are not a complete replacement for BM25 full-text retrieval. In practice, three-way recall with BM25 + sparse + dense usually outperforms any two-way combination.
• At the index level, SINDI can also serve BM25-style scoring: use inverse document frequency as the query-side term weight, and use term-frequency-based weights as the document-side term value.

Common configurations

1. Flat brute-force sparse index. Keep all non-zero terms in the inverted index (doc_prune_ratio: 0.0), disable the flat reranker (use_reorder: false), and disable quantization (use_quantization: false). This is the simplest high-recall baseline.
2. Pruned high-accuracy index. Prune most low-weight terms during build (doc_prune_ratio: 0.4), keep the flat copy for reranking (use_reorder: true), and enable quantization to shrink inverted-list memory (use_quantization: true). This is a common balance between memory and recall.
3. Pruned high-accuracy index with compressed reranking. Use the same pruning and inverted-list quantization as above, but set rerank_type: "fp16" together with use_reorder: true for a precision-oriented reduction in forward-store memory, or select dmq8 for stronger compression.
4. Very large sparse vocabularies. When term IDs are sparse within the uint32 range, such as hash-based tokenizers, external vocabulary IDs, or vocabularies with large gaps, enable remap_term_ids: true. This avoids managing many empty posting lists and helps stay below the term_id_limit ceiling.
5. Read-only low-memory build. Add immutable: true, normally together with use_quantization: "fp16" and remap_term_ids: true, when peak build memory matters more than build speed and the finished index will not receive incremental writes.

Mark remove

SINDI supports RemoveMode::MARK_REMOVE. Calling Remove(ids) (the default mode) tombstones the given ids so they no longer appear in search results; GetNumElements() drops accordingly and GetNumberRemoved() reports the running total. Removing an id that is absent or already removed is a no-op. RemoveMode::FORCE_REMOVE is not supported and returns an error.

Mark-removed documents still occupy memory until the index is rebuilt; the space is not physically reclaimed.

See also

• Creating an Index
• Index Parameters
• k-Nearest Neighbor Search

SINDI_V2

SINDI_V2 is VSAG’s term-first sparse-vector index. It uses the same windowed inverted-list scoring model and 1 - inner_product distance as SINDI, but persists postings by term so a search can read only the lists needed by the query.

• Factory entry: sindi_v2
• Source: src/algorithm/sindi_v2/
• Required dtype: sparse
• Required metric_type: ip

Storage layout

Each term payload stores only non-empty windows:

non_empty_window_count
ordered {window_id, posting_count}[]
local_doc_ids[]
alignment padding
encoded_values[]

At query time, SINDI_V2 expands the sparse metadata into window_count + 1 window offsets. A query loads postings only for its retained terms through reader_io, mmap_io, buffer_io, async_io, or an in-memory backend.

This differs from SINDI’s window-first serialization. The two factory entries therefore require different persisted formats and must not be used interchangeably when loading an index.

Quick start

#include <vsag/vsag.h>

std::string params = R"({
    "dtype": "sparse",
    "metric_type": "ip",
    "dim": 1024,
    "index_param": {
        "term_id_limit": 30000,
        "window_size": 50000,
        "doc_prune_ratio": 0.1,
        "use_quantization": true,
        "use_reorder": true,
        "remap_term_ids": true,
        "term_io": {
            "type": "buffer_io",
            "file_path": "/tmp/sindi_v2.terms"
        },
        "rerank_io": {
            "type": "block_memory_io"
        }
    }
})";
auto index = vsag::Factory::CreateIndex("sindi_v2", params).value();
index->Build(base);

auto result = index->KnnSearch(
    query, 10,
    R"({"sindi_v2": {
        "n_candidate": 100,
        "filter_callback_limit": 10000,
        "query_prune_ratio": 0.1,
        "term_prune_ratio": 0.2,
        "term_retain_threshold": 10000
    }})").value();

Build parameters

Build parameters live under index_param.

File-backed term_io supports mmap_io, buffer_io, and async_io, and requires file_path. If a file-backed rerank_io omits file_path, VSAG derives it as <term_io.file_path>.rerank.

rerank_type: "fp16" requires use_reorder: true and supports the same rerank I/O and layout options as fp32. rerank_layout > 0 requires use_reorder: true. rerank_type: "dmq8" requires rerank_layout: 0 and the default block_memory_io rerank backend.

Host filtering

SINDI_V2 supports the same string host build and KNN-query metadata contract as SINDI. Both mutable and immutable indexes are supported. It uses the shared host grouping and routing component while retaining its own term-first posting storage. Host membership is enforced during posting-window search, including multiple ranges created by mutable Add(). The empty-string missing-host value, persisted internal dictionary, mutable Add() metadata rules, streaming serialization, and the KNN-only scope are the same as SINDI.

Publish-time filtering

SINDI_V2 supports the same SINDI Unix-second input, UTC-day matching, and inclusive time-range contract. The two indexes share one metadata filtering component for time-only, host-only, and combined time-and-host KNN routing. SINDI_V2 retains its term-first posting layout. Publish-time filtering supports mutable and immutable indexes with either use_reorder setting and is preserved by standard and streaming serialization; range search remains unfiltered. A mutable time-aware SINDI_V2 is build-once and follows the same initial Build() or first-Add() and later-Add() rejection rules as SINDI. Base timestamp 0 uses the same missing-time semantics: unfiltered and host-only queries include those documents, while time queries exclude them. Exact day filtering disables term-level posting pruning in each selected window, so time queries may scan more postings than host-only queries. Host-only queries on time-enabled indexes share the boundary-window behavior documented for SINDI.

Search parameters

Search parameters live under {"sindi_v2": {...}}.

After combining the ratio and threshold limits, SINDI V2 scans at least one posting from every non-empty term list.

SINDI V2 chooses the heap-insertion strategy automatically from the build-time doc_prune_ratio and search-time query_prune_ratio. With the current 0.1 threshold, it uses distance-array insertion when both ratios are <= 0.1; if either ratio is greater than 0.1, it uses term-list heap insertion.

Choosing between SINDI and SINDI_V2

Use SINDI when the full sparse index remains in memory and window-first serialization is appropriate. Use SINDI_V2 when persisted postings should be organized by term or when searches should fetch only the query’s term lists from external storage.

SIMQ

SIMQ (Single Index for Multi-vector Query) is VSAG’s index for multi-vector retrieval — the kind of data where each document is a set of token-level vectors rather than a single embedding. This pattern arises in late-interaction models such as ColBERT, where a document is represented by one vector per token and relevance is computed via MaxSim (sum of maximum per-query-token similarities).

• Source: src/algorithm/simq/

How it works

1. Dynamic clustering of token vectors. At build time, all token vectors across every document are extracted into a flat pool and clustered using an HGraph-based dynamic clustering algorithm. The initial cluster centers are sampled at a ratio controlled by init_cluster_ratio; clusters that grow beyond max_cluster_size are split incrementally.
2. Representative graph for coarse search. A representative HGraph is built over the cluster centroids. At query time, each query token searches this graph to find its nearest clusters (controlled by coarse_k). The cluster scores are accumulated across all query tokens to produce a candidate set.
3. Exact MaxSim reranking. The top rerank_k candidates are re-scored by reading back the original token vectors from disk (or memory) and computing the exact MaxSim similarity between query tokens and document tokens.

The combination of cluster-level coarse search and exact reranking gives SIMQ a tunable recall/latency tradeoff for multi-vector workloads.

Quick start

#include <vsag/vsag.h>

std::string build_params = R"({
    "dtype": "float32",
    "metric_type": "ip",
    "dim": 256,
    "index_param": {
        "base_io_type": "async_io",
        "base_file_path": "/path/to/simq_base_codes.bin",
        "init_cluster_ratio": 0.1,
        "max_cluster_size": 160,
        "split_start_idx": 80,
        "random_seed": 42,
        "coarse_k": 50,
        "rerank_k": 1000
    }
})";
auto index = vsag::Factory::CreateIndex("simq", build_params).value();

// Build a dataset of MultiVector.
// Each document has a variable number of token vectors, each of dimension `dim`.
std::vector<vsag::MultiVector> base_mvs(num_docs);
std::vector<int64_t> ids(num_docs);
for (int64_t i = 0; i < num_docs; ++i) {
    base_mvs[i].len_ = doc_token_counts[i];             // number of tokens in doc i
    base_mvs[i].vectors_ = doc_token_vectors[i];        // flat array: len_ * dim floats
    ids[i] = i;
}
auto base = vsag::Dataset::Make();
base->NumElements(num_docs)
    ->Dim(dim)
    ->Ids(ids.data())
    ->MultiVectors(base_mvs.data())
    ->MultiVectorDim(dim)
    ->Owner(false);
index->Build(base);

// Search with a multi-vector query.
vsag::MultiVector query_mv;
query_mv.len_ = query_token_count;
query_mv.vectors_ = query_token_vectors;
auto query = vsag::Dataset::Make();
query->NumElements(1)
    ->Dim(dim)
    ->MultiVectors(&query_mv)
    ->MultiVectorDim(dim)
    ->Owner(false);

std::string search_params = R"({
    "simq": {
        "coarse_k": 600,
        "rerank_k": 5000
    }
})";
auto result = index->KnnSearch(query, /*topk=*/100, search_params).value();

// Read results.
const int64_t* result_ids = result->GetIds();
const float* result_dists = result->GetDistances();
int64_t result_count = result->GetDim();
for (int64_t i = 0; i < result_count; ++i) {
    int64_t id = result_ids[i];
    float dist = result_dists[i];
}

Build parameters

SIMQ-specific build parameters live under index_param. The common fields dim, dtype, and metric_type are top-level. dtype must be "float32" and metric_type must be "ip".

• dim — shared across all documents and queries.
• base_io_type — supported values: async_io, uring_io, memory_io, block_memory_io, buffer_io, mmap_io, reader_io. Native uring_io requires a build with liburing; otherwise it falls back to buffer_io.
• base_file_path — the default is a placeholder; provide a real path when using a disk-backed type (async_io, uring_io, buffer_io, mmap_io).
• init_cluster_ratio — range (0, 1]. Smaller values yield fewer, larger clusters; larger values produce more, finer-grained clusters.
• max_cluster_size — must be > 1.
• split_start_idx — typically half of max_cluster_size. Must be in (1, max_cluster_size).
• coarse_k, rerank_k — must be > 0.

Choosing cluster parameters. init_cluster_ratio and max_cluster_size together control the number and size of clusters. A smaller init_cluster_ratio with a larger max_cluster_size yields fewer clusters and faster coarse search at the cost of recall. Start with init_cluster_ratio = 0.1–0.2 and max_cluster_size = 2 × split_start_idx, then tune with the search parameters.

Search parameters

Search-time parameters live under the simq sub-object:

• coarse_k — overrides the build-time value. Larger values increase the candidate pool and improve recall at the cost of latency.
• rerank_k — overrides the build-time value. Larger values improve recall at the cost of more disk reads and compute.
• When omitted, the build-time defaults are used. Both values must be > 0 when explicitly set.

auto result = index->KnnSearch(
    query, topk,
    R"({"simq": {"coarse_k": 600, "rerank_k": 5000}})").value();

Search statistics

KnnSearch and RangeSearch attach a JSON statistics object to the returned dataset. Read the complete object or request individual values:

std::cout << result->GetStatistics() << '\n';
auto values = result->GetStatistics(
    {"simq_coarse_candidate_count", "simq_rerank_candidate_count"});

These counters make it possible to distinguish a narrow coarse candidate pool from filtering, reranking, and output-limit effects when tuning recall and latency.

When to use SIMQ

• Late-interaction retrieval with ColBERT or similar models where each document is a bag of token-level vectors and relevance is computed via MaxSim.
• Multi-vector relevance where a single embedding per document loses too much information and fine-grained token-level matching is needed.
• Large-scale multi-vector corpora where brute-force MaxSim is too slow and a two-stage coarse-then-rerank pipeline provides the right recall/latency tradeoff.

SIMQ only accepts float32 multi-vector data with inner-product similarity. It does not accept single dense vectors or sparse vectors (use HGraph or SINDI for those).

Practical guidance

• Scaling coarse_k and rerank_k. Increasing coarse_k widens the cluster-level candidate net; increasing rerank_k admits more documents to exact scoring. In practice, rerank_k has a larger impact on recall but also on latency because each additional candidate requires a disk read and full MaxSim computation.
• IO type selection. Use async_io for large corpora that do not fit in memory. Use memory_io or block_memory_io when the multi-vector data fits in RAM for the lowest reranking latency.
• Cluster sizing. Set max_cluster_size to roughly twice split_start_idx. The split point determines how the token vectors are partitioned when a cluster overflows; centering it keeps the two halves balanced.

MultiVector field reference

See also

• Creating an Index
• Index Parameters
• k-Nearest Neighbor Search

Pyramid

Pyramid is VSAG’s hierarchical, path-partitioned graph index. A vector can be tagged with one or multiple path strings such as "a/d/f", and Pyramid builds a graph per node in those path trees. At query time you supply one or more path prefixes, and Pyramid restricts the search to the corresponding sub-trees.

This is ideal for multi-tenant deployments, tag-partitioned catalogs, or any scenario where one logical index serves many groups that must not cross-contaminate results.

• Source: src/algorithm/pyramid.{h,cpp}, src/algorithm/pyramid_zparameters.{h,cpp}
• Example (single hierarchy): examples/cpp/107_index_pyramid.cpp
• Example (multi-hierarchy): examples/cpp/112_index_pyramid_multi_hierarchy.cpp

How it works

1. Path tree. Each vector can carry independent paths in addition to its id. Paths use / as separator (e.g. "tenant_a/lang_en/topic_news"). Pyramid builds one sub-index for every path prefix seen during build. The vector data and id are stored once even when the vector belongs to multiple paths.
2. Per-level sub-graphs. By default every level gets its own proximity graph. Use no_build_levels to skip levels that are too small or too coarse to benefit from graph indexing — those levels still exist as passthrough containers, but search degrades to a scan.
3. Graph construction. Each sub-graph is built with the same machinery as HGraph: nsw insertion or odescent with graph_iter_turn, neighbor_sample_rate, and alpha for pruning. Base vectors are stored in base_quantization_type; optional reordering keeps a high-precision copy.
4. Search. Query vectors also carry a path. The search walks down the tree to the most specific sub-graph matching the query path and runs a graph search there with ef_search (and subindex_ef_search for intermediate levels).

Quick start

#include <vsag/vsag.h>

std::string params = R"({
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 128,
    "index_param": {
        "base_quantization_type": "sq8",
        "max_degree": 32,
        "alpha": 1.2,
        "graph_type": "odescent",
        "graph_iter_turn": 15,
        "neighbor_sample_rate": 0.2,
        "no_build_levels": [0, 1],
        "use_reorder": true,
        "build_thread_count": 16
    }
})";
auto index = vsag::Factory::CreateIndex("pyramid", params).value();

// Build with per-vector paths.
auto base = vsag::Dataset::Make();
base->NumElements(n)
    ->Dim(128)
    ->Ids(ids)
    ->Paths(paths)          // std::string* of length n, e.g. "a/d/f"
    ->Float32Vectors(data)
    ->Owner(false);
index->Build(base);

// Search restricted to a path prefix.
std::string query_path = "a/d";
auto query = vsag::Dataset::Make();
query->NumElements(1)
    ->Dim(128)
    ->Float32Vectors(q)
    ->Paths(&query_path)
    ->Owner(false);
auto result = index->KnnSearch(
    query, /*topk=*/10,
    R"({"pyramid": {"ef_search": 100}})").value();

Input data type

The public Build, Add, and search paths currently accept FP32 vectors supplied with Dataset::Float32Vectors; set dtype to "float32". base_quantization_type selects internal encoding and storage and does not by itself enable FP16, BF16, or INT8 input.

Build parameters

Build-time parameters live under index_param.

PiPNN supports Pyramid builds with dtype: "float32" and metric_type set to "l2", "ip", or "cosine". It batch-builds every constructed graph in each hierarchy; with root_graph_type: "multi_layer", this also includes every root routing layer. Search, incremental Add, removal, duplicate handling, reorder, and serialization retain the standard Pyramid behavior. Levels in no_build_levels are still skipped. The pipnn_* values are global to the Pyramid index; hierarchy objects may continue to override max_degree and alpha, and those overrides are applied when PiPNN builds that hierarchy. ef_construction does not tune PiPNN.

RaBitQ split configuration

Set all five parameters together to enable RaBitQ x+y split storage and reordering:

{
    "use_reorder": true,
    "base_quantization_type": "rabitq",
    "precise_quantization_type": "rabitq",
    "rabitq_bits_per_dim_base": 3,
    "rabitq_bits_per_dim_precise": 5
}

Pyramid uses split-code code-to-code distances for incremental flat-to-graph promotion, so it does not retain an internal FP32 copy by default. Set store_raw_vector to true at build time when raw-vector access and complete analyzer metrics are required.

MRLE with split RaBitQ

Pyramid can truncate embeddings trained with Matryoshka Representation Learning before encoding them as split RaBitQ codes:

{
    "base_quantization_type": "tq",
    "tq_chain": "mrle, rabitq",
    "mrle_dim": 1280,
    "precise_quantization_type": "rabitq",
    "rabitq_bits_per_dim_base": 3,
    "rabitq_bits_per_dim_precise": 5,
    "use_reorder": true
}

The 3-bit filter planes are used for graph traversal and the 5-bit supplement planes for reordering; both encode the same truncated vector. Pyramid uses split code-to-code distances for graph promotion and does not retain the original FP32 vectors. Metrics that require decodable vectors are marked unavailable unless store_raw_vector was enabled at build time. Truncation can reduce recall unless the embedding model was trained for prefix dimensions.

Build cache

ExportCache captures per-hierarchy, per-node NSW graph seeds and ImportCache makes them available to a later Build. Cache data uses the index cache payload format, not the streaming index serialization format. Set persist_source_id: true before footer-serializing an index whose cache will be reused, and provide a unique Dataset::SourceID and external label for every vector in both builds. Cache warm builds apply only to graph_type: "nsw"; ODescent, missing source IDs, and repeated source IDs or labels fall back to a normal cold build (which retains its normal repeated-label rejection behavior). ef_construction is not an eligibility condition. At least 80% of input source IDs must overlap the imported cache. Cache misses are constructed normally. Single-layer root hits receive forward-row repair; multi-layer nodes rebuild routing overlays, which are not cached.

With support_duplicate: true, Pyramid stores explicit per-graph group membership and the actual adjacency-row owner, not the minimum label or inner ID. Warm construction remaps SourceIDs and verifies current graph membership and construction-code equality. Missing or moved representatives, changed equivalence classes and unusable class rows turn the affected classes into misses; unrelated valid classes remain reusable. Removed aliases alone do not invalidate their class. Newly merged code classes are conservatively rebuilt. Hash-keyed ordered indexes compare exact construction-code bytes to resolve collisions, rather than assuming hash equality. At least 80% of each graph’s memberships must remain reusable; missing/legacy group metadata or insufficient reuse triggers graph-level cold fallback. All-identical graphs without useful cached adjacency still cold-build. Representative adjacency is restored before aliases, and edges to invalid classes are filtered. Aliases count as memberships, not restored edges or routing entries.

Concurrent insertion uses a transient graph-local exact-code representative registry, holding only the corresponding admission stripe through representative publication. It references existing construction codes instead of copying full vectors and is rehydrated when needed after loading an index. After cold construction and warm refinement, duplicate-enabled NSW Build checks both forward reachability from each bottom graph’s entry and return reachability to that entry. When needed, bounded, geometrically selected bridges preserve the protected forward tree and maximum degree. Together these checks ensure strong connectivity among the graph’s physical representatives, including those selected as query-specific entries by routed descent. Return-path checking uses CSR reverse adjacency with O(R + E) temporary memory for R representatives and E edges, released per graph. This is a Build-time invariant, not a guarantee for arbitrary later Add operations. Finite-budget approximate search can still miss whole vector groups. No universal recall or construction speedup is guaranteed. After deserialization, sparse empty adjacency rows retain physical-owner identity. Legacy dense/compressed storage can lose that identity for an isolated empty duplicate group; admission first preserves owners observable through rows, incoming edges or routing, then normalizes an otherwise unobservable persisted duplicate group without changing its labels. This does not recover historical owner identity or restore arbitrary incremental graph connectivity. The one-time legacy admission scan uses O(H + A + E) traversal work and O(H) visitation memory, where H is the stored ID high-water mark, A is the visited duplicate membership count and E is the traversed edge count; exact-code ordered-index operations add their usual comparison cost.

Duplicate-aware cache payloads use a versioned Pyramid-only format. This reader accepts legacy ordinary caches; older readers cannot read the new duplicate payload. Ordinary caches without group metadata retain the legacy format. HGraph cache and index serialization formats are unchanged. GetStats() separates vector and graph-membership hit/miss counts from restored-edge counts; graph fallback contributes misses, not restored groups.

Search parameters

Search-time parameters live under the pyramid sub-object:

auto result = index->KnnSearch(
    query, topk,
    R"({"pyramid": {"ef_search": 200, "subindex_ef_search": 80}})").value();

Multi-Hierarchy Support

A single Pyramid index can maintain multiple independent path trees, each identified by a name (e.g. "site", "category"). Vectors share IDs and data across all hierarchies — only the paths differ. Each hierarchy can optionally override graph construction parameters.

This is useful when the same set of vectors needs to be partitioned along different dimensions simultaneously. For example, an e-commerce platform might partition products by site (site-a/lang-en) and by category (electronics/phones) at the same time, and search can target either hierarchy independently.

Build configuration

Add a hierarchies array inside index_param. Each element is either:

• A string (inherits all top-level params): "site"
• An object with name and optional per-hierarchy overrides: {"name": "category", "max_degree": 64, "no_build_levels": [0]}

Overridable per-hierarchy parameters: max_degree, ef_construction, alpha, no_build_levels, index_min_size, root_graph_type.

root_graph_type: "multi_layer" changes only the selected hierarchy’s root. Its bottom graph uses the top-level graph_storage_type: Flat by default, or Compressed to trade construction and search speed for lower graph memory. Sparse routing graphs choose a better entry point before the bottom search; child graphs remain sparse. NSW Build and incremental Add jointly construct the route and bottom layers with the same HGraph-style insertion protocol. PiPNN Build batch-constructs both layers. Combining multi_layer with odescent is rejected during parameter validation. Bottom and routing edges use the precise codes when an independent precise store exists, otherwise they use the base codes. Query traversal continues to use the base codes, and final reordering uses the configured reorder source.

{
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 128,
    "index_param": {
        "base_quantization_type": "sq8",
        "max_degree": 32,
        "alpha": 1.2,
        "graph_type": "odescent",
        "graph_iter_turn": 15,
        "neighbor_sample_rate": 0.2,
        "no_build_levels": [0, 1],
        "use_reorder": true,
        "build_thread_count": 16,
        "hierarchies": [
            "site",
            {"name": "category", "max_degree": 64, "no_build_levels": [0]}
        ]
    }
}

Dataset API for named hierarchies

Use the overloaded Paths(hierarchy_name, paths) methods to assign paths per hierarchy. The same Ids() and Float32Vectors() are shared across all hierarchies. The pointer overload keeps the existing one-path-per-vector form:

auto base = vsag::Dataset::Make();
base->NumElements(n)
    ->Dim(128)
    ->Ids(ids)
    ->Float32Vectors(data)
    ->Paths("site", site_paths)         // std::string* of length n
    ->Paths("category", category_paths) // independent paths for 2nd hierarchy
    ->Owner(false);
index->Build(base);

Retrieving paths by ID

Set the top-level build parameter store_paths to true to retain the original paths for ID-based retrieval. Select DATA_FLAG_PATH in GetDataByIdsWithFlag; the returned paths follow the requested ID order. Use GetPaths() for the default unnamed hierarchy and GetPaths(hierarchy_name) for a named hierarchy:

int64_t requested_ids[] = {product_id_b, product_id_a};
auto data = index->GetDataByIdsWithFlag(
    requested_ids, 2, DATA_FLAG_ID | DATA_FLAG_PATH).value();

const std::string* site_paths = data->GetPaths("site");
const std::string* category_paths = data->GetPaths("category");

GetDataByIds and GetDataByIdsWithFlag calls without DATA_FLAG_PATH do not attach path arrays. Selecting DATA_FLAG_PATH while store_paths is false returns an invalid-argument error. When path storage is enabled, these legacy getters include a hierarchy only if every requested ID has exactly one recorded path in that hierarchy. If any requested ID has no recorded path or multiple paths, its getter returns nullptr; other hierarchies whose requested paths are complete are returned. In single-hierarchy mode, the same rule applies to GetPaths().

Use the structured overload to retrieve every path regardless of the stored representation:

std::vector<std::vector<std::string>> tag_paths;
if (data->GetPaths("tag", tag_paths)) {
    // tag_paths[i] contains every path for requested_ids[i].
}

To assign multiple independent paths to one vector in the same hierarchy, pass a nested vector. The outer vector has one entry per dataset element; each inner vector has one or multiple paths:

std::vector<std::vector<std::string>> tag_paths = {
    {"technology", "military"}, // vector 0 belongs to both paths
    {"sports"},                  // vector 1 belongs to one path
    {""},                        // vector 2 belongs to the hierarchy root
};

auto base = vsag::Dataset::Make();
base->NumElements(3)
    ->Dim(128)
    ->Ids(ids)
    ->Float32Vectors(data)
    ->Paths("tag", std::move(tag_paths))
    ->Paths("site", site_paths) // legacy pointer form can coexist
    ->Owner(false);
index->Build(base);

An empty inner vector is invalid. An inner vector containing "" assigns the vector to the root. Duplicate paths and shared prefixes are inserted once per tree node. Add() accepts the same form, and serialization preserves every resulting path assignment.

Searching a specific hierarchy

Specify which hierarchy to search via "hierarchies" in the search parameters. The query dataset must also set its path on the matching hierarchy name:

auto query = vsag::Dataset::Make();
query->NumElements(1)
    ->Dim(128)
    ->Float32Vectors(q)
    ->Paths("site", &query_path)   // target the "site" hierarchy
    ->Owner(false);

auto result = index->KnnSearch(
    query, /*topk=*/10,
    R"({"pyramid": {"ef_search": 100, "hierarchies": ["site"]}})").value();

The legacy query form uses | for a union of path alternatives, for example "technology|military"; a vector reachable through both alternatives appears once in the result. In this legacy string form, | is reserved and has no escaping syntax. A structured query avoids that delimiter convention and also allows a literal | inside a path segment:

auto query = vsag::Dataset::Make();
query->NumElements(1)
    ->Dim(128)
    ->Float32Vectors(q)
    ->Paths("tag", std::vector<std::vector<std::string>>{{"technology", "military"}})
    ->Owner(false);

Incremental insertion (Add)

Add() works the same as Build() — provide either single or structured named paths and the index inserts each accepted vector into all matching paths:

auto new_data = vsag::Dataset::Make();
new_data->NumElements(count)
    ->Dim(128)
    ->Ids(new_ids)
    ->Float32Vectors(new_vectors)
    ->Paths("site", new_site_paths)
    ->Paths("category", new_cat_paths);
index->Add(new_data);

RangeSearch

RangeSearch also supports hierarchy selection via the same search parameters:

auto result = index->RangeSearch(
    query, /*radius=*/20.0f,
    R"({"pyramid": {"ef_search": 100, "hierarchies": ["category"]}})").value();

Serialize & Deserialize

Multi-hierarchy indexes serialize and deserialize transparently. The serialized format includes all hierarchy names and their graph structures. With store_paths: true, both regular and streaming serialization also persist the retained original paths, making them available through GetDataByIdsWithFlag after deserialization. With the default false, the graph hierarchy is persisted but the original per-ID paths are not:

// Serialize
auto binary_set = index->Serialize().value();

// Deserialize into a new index (must use the same build params)
auto new_index = vsag::Factory::CreateIndex("pyramid", build_params).value();
new_index->Deserialize(binary_set);

When to use Pyramid

• Multi-tenant services where each tenant must see results only from its own partition, and you would otherwise maintain one index per tenant.
• Content catalogs with hierarchical tags (language / region / category) where queries always scope to a known prefix.
• Workloads with many small partitions: no_build_levels and index_min_size let you skip graph construction for partitions too small to benefit.

If you don’t need path-based scoping, HGraph is simpler and generally faster.

Use Index Analysis to inspect Pyramid tree structure, per-subindex quality, sampled base recall, and duplicate ratios reported by GetStats(). For each hierarchy, root_graphs reports root_graph_type, bottom_graph_storage_type, bottom_graph_node_count, bottom_graph_size, route_graph_count, route_node_counts, and route_graph_size. AnalyzeIndexBySearch also reports path-scoped query recall, distance, latency, and, when reorder is enabled, quantization metrics. Its query dataset must carry the same default or named-hierarchy paths required by KnnSearch. For a batched dataset, the outer path collection has one row per query: the legacy overload supplies one path string per row (and uses | for a union), while the structured overload supplies one or many atomic paths per row and permits literal | characters. The analyze_index tool cannot currently load hierarchy paths from its dense query file, so use the C++ API for path-scoped dynamic analysis.

Mark remove

Pyramid supports RemoveMode::MARK_REMOVE. Calling Remove(ids) (the default mode) tombstones the given ids: they are excluded from subsequent search results, GetNumElements() drops by the number removed, and GetNumberRemoved() reports the running total. Removing an id that is absent or already removed is a no-op. RemoveMode::FORCE_REMOVE is not supported and returns an error.

Mark-removed vectors still occupy memory until the index is rebuilt; the space is not physically reclaimed.

Label lookup and persistence

Label 0 is valid. Reserved capacity does not create labels: CheckIdExist(0) is false when no vector has that label, and single-ID CalcDistanceById returns an error for a missing or mark-removed label.

Pyramid writes only populated label slots using the existing length-prefixed vector format. When reading older payloads containing unused slots, it uses the stored vector count to discard the unused suffix and rebuild label mappings. Both seekable and streaming formats support this recovery. Older readers can still parse newly written payloads, but do not gain the corrected lookup behavior; upgrade the reader as well.

See also

• Creating an Index
• Index Parameters
• Graph Enhancement
• HGraph

BruteForce

BruteForce is VSAG’s exact, flat index. At query time it scores the query against every vector in the corpus and returns the true top-k — no graph traversal, no inverted lists, no approximation. Its main role is to be the ground-truth baseline that approximate indexes (HGraph, IVF, …) are evaluated against, but it is also a reasonable production choice for small corpora or for workloads where 100% recall is mandatory.

• Source: src/algorithm/bruteforce/bruteforce.{h,cpp}
• Example: examples/cpp/105_index_brute_force.cpp

How it works

1. Build. Vectors are stored in a single flat data cell encoded by base_quantization_type (default fp32 — i.e. raw). No graph, no clustering, no training is performed for the uncompressed quantizers; PQ/SQ-style quantizers that require training will still run their training pass when used.
2. Add. New vectors are appended to the flat store. There is no rebalancing or rebuild cost.
3. Search. For each query the distance is computed against every stored vector under the configured metric_type (l2, ip, or cosine), then a top-k heap returns the closest ids. Search uses SIMD kernels and supports intra-query parallelism — a single query can be split across multiple threads via the parallelism search parameter (see BruteForce::SearchWithRequest in src/algorithm/bruteforce/bruteforce.cpp).

Because the index keeps every vector verbatim (modulo the chosen quantizer), the result is exact when base_quantization_type is fp32 and is the standard reference used to compute ground truth in the eval_performance tool.

Quick start

#include <vsag/vsag.h>

std::string params = R"({
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 128
})";
auto index = vsag::Factory::CreateIndex("brute_force", params).value();

// Build.
auto base = vsag::Dataset::Make();
base->NumElements(n)->Dim(128)->Ids(ids)->Float32Vectors(data)->Owner(false);
index->Build(base);

// Search — no index-specific knobs; pass an empty JSON object (or set `parallelism`).
auto query = vsag::Dataset::Make();
query->NumElements(1)->Dim(128)->Float32Vectors(q)->Owner(false);
auto result = index->KnnSearch(query, /*topk=*/10, "{}").value();

A full runnable program is at examples/cpp/105_index_brute_force.cpp.

Input data type

The public Build, Add, KnnSearch, RangeSearch, and UpdateVector paths accept FP32 vectors only. At runtime, supply vectors via Dataset::Float32Vectors. At index creation, set dtype to "float32"; dtype: "int8" is not supported when creating a BruteForce index.

The base_quantization_type parameter controls the index’s internal encoding and storage, not the input type. Selecting an internal fp16, bf16, or other quantizer does not enable FP16/BF16 input.

Build parameters

The minimal config consists of the three top-level fields (dtype, metric_type, dim). For most uses no index_param is needed — that is the form shown in example 105. Advanced users can pass an index_param object to enable quantization or storage tweaks:

Note on store_raw_vector. The store_raw_vector flag is parsed by the shared InnerIndexParameter but BruteForce does not consult it when deciding whether GetRawVectorByIds is available. On BruteForce, raw-vector retrieval is enabled strictly when base_quantization_type is fp32 and either the metric is not cosine or the quantizer is configured to hold the per-vector norms (hold_molds). Setting store_raw_vector: true on BruteForce currently has no observable effect on the capability flags — use HGraph or IVF if you need a quantized index that still answers GetRawVectorByIds.

Example with sq8 quantization for memory savings while keeping linear scan semantics:

{
    "dtype": "float32",
    "metric_type": "ip",
    "dim": 128,
    "index_param": {
        "base_quantization_type": "sq8"
    }
}

When base_quantization_type is set to a quantizer that requires training (sq8, sq8_uniform, sq4_uniform, pq, pqfs, rabitq), Build will run the training pass on the supplied dataset before adding vectors; the resulting recall is no longer 100%. Only fp32, fp16, and bf16 skip training and preserve exact distances (modulo numeric precision).

Search parameters

BruteForce does not expose any index-specific search knobs (no ef, nprobe, etc.), but the generic IndexSearchParameter fields are honored:

// Single-threaded scan (default).
auto r1 = index->KnnSearch(query, topk, "{}").value();

// Use 8 threads to scan a single query in parallel.
auto r2 = index->KnnSearch(query, topk, R"({"parallelism": 8})").value();

// RangeSearch uses the same parallelism parameter.
auto r3 = index->RangeSearch(query, radius, R"({"parallelism": 8})").value();

For range search semantics, see Range Search.

Removing vectors

BruteForce supports both RemoveMode::MARK_REMOVE and RemoveMode::FORCE_REMOVE; neither mode needs an HGraph-style support_force_remove setting.

When use_attribute_filter: true is enabled, neither removal mode is available. Rebuild the index instead if attribute-filtered data must be deleted.

• MARK_REMOVE is the default. It records a tombstone, so the id is excluded from later searches while its vector storage remains allocated. GetNumElements() excludes marked ids and GetNumberRemoved() reports their count.
• FORCE_REMOVE physically removes each requested vector. It moves the last internal slot into the vacated slot when necessary and keeps the moved vector’s external id intact. Successful force removals do not add tombstones; pre-existing marked removals remain reflected by GetNumberRemoved().

index->Remove(std::vector<int64_t>{id1, id2}, vsag::RemoveMode::MARK_REMOVE);
index->Remove(std::vector<int64_t>{id3, id4}, vsag::RemoveMode::FORCE_REMOVE);

Physical removal is synchronous and more expensive than marking. It takes the index’s exclusive global lock, so it waits for in-flight searches and prevents new searches while the swap-and-remove operation runs. Batch ids when possible and avoid force removal on latency-critical paths.

By default, BruteForce uses block_memory_io for vector storage. After every successful force-removal batch, its logical size is reduced to the live entry count and trailing complete blocks are released; the final partial block remains allocated. The optional extra-information store follows the same block-granular behavior. To avoid repeated full-table copies, the label table reclaims its backing allocation when its live entry count falls to at most half of its current capacity. GetMemoryUsage() then reflects the compacted index. This is index allocation accounting, not a promise that the process allocator immediately returns memory to the operating system or that RSS drops.

Capabilities

BruteForce advertises the following capability flags (see BruteForce::InitFeatures in src/algorithm/bruteforce/bruteforce.cpp):

Notably not supported by BruteForce: SUPPORT_UPDATE_ID_CONCURRENT and SUPPORT_EXPORT_MODEL.

When to use BruteForce

• Recall baseline. Compute the ground truth that approximate indexes are scored against (this is what the eval_performance tool does).
• Tiny corpora. A few hundred to a few hundred thousand vectors, where the cost of a full scan is acceptable and you want to skip tuning altogether.
• Strict-recall requirements. Use cases that cannot tolerate any approximation error.
• Quantization experiments at small scale. Reuse the same scan pipeline but compare different base_quantization_type settings without the confounding effect of a graph or inverted-list structure.

For anything larger, prefer HGraph (latency-sensitive, high recall) or IVF (throughput-oriented, memory-friendly).

See also

• Creating an Index
• k-Nearest Neighbor Search
• Range Search
• Attribute Filter (Hybrid Search)
• Evaluation Tool

Quantization

Vector quantization is the central memory/recall lever in VSAG. Every index type stores vectors through a base quantizer (configured by base_quantization_type), and may keep a second precise quantizer for re-ranking (precise_quantization_type + use_reorder: true). This chapter documents each supported quantizer: what it does, what JSON parameters it takes, when it needs training, which metrics it supports, and when to choose it.

Storage and search pipeline

                 +---------------------+
   raw vector -->|  optional transform |   (TQ chain: pca / rom / fht / mrle)
                 +----------+----------+
                            |
                            v
                 +---------------------+
                 |   base quantizer    |   fp32 / fp16 / bf16 /
                 |                     |   sq8 / sq4 / sq8_uniform /
                 |                     |   sq4_uniform / pq / pqfs /
                 |                     |   rabitq
                 +----------+----------+
                            |
                            v
                  +-------------------+
                  |   index storage   |   (HGraph / IVF / Pyramid /
                  |                   |    BruteForce / SINDI)
                  +---------+---------+
                            |
                            v
                   graph / list walk
                            |
            +---------------+-----------------+
            |                                 |
   use_reorder: false                use_reorder: true
            |                                 |
            v                                 v
       top-K result               +---------------------+
                                  | precise quantizer   |  re-rank
                                  | (fp32 default;      |
                                  |  fp16/bf16/sq8 OK)  |
                                  +----------+----------+
                                             |
                                             v
                                        top-K result

use_reorder and precise_quantization_type are not specific to any single quantizer — they apply whenever the index supports reordering (see HGraph, IVF, Pyramid).

Supported quantizers at a glance

The factory in src/datacell/flatten_interface.cpp dispatches to the concrete quantizer based on the JSON type field.

int8 and sparse are not exposed as general-purpose base_quantization_type values:

• int8 is selected automatically when dtype: "int8" is used; it is not a compression mode.
• sparse backs the inverted lists of SINDI and is not selectable on dense indexes.

Training requirement

Quantizers marked yes above implement the NEED_TRAIN flag and require either Build (which trains internally on the input vectors) or an explicit Train call before Add. See Build and Train for the full lifecycle.

For HGraph the training data is the base vectors passed to Build; for IVF the centroids are trained first and the residuals fed to the configured base quantizer.

Metric compatibility

All quantizers documented here support the three dense metrics (l2 / ip / cosine). For cosine, the index normalizes vectors before quantization, so the underlying quantizer never sees the original magnitude. A few practical notes:

• pq / pqfs perform their distance lookup tables per subspace; very low pq_dim (≤ 4) on ip / cosine is more sensitive to anisotropy than l2.
• rabitq works best when input vectors are decorrelated — either turn on rabitq_use_fht / rabitq_pca_dim, or wrap with a tq chain like "pca, rom, rabitq".

Choosing a quantizer

A pragmatic decision tree:

1. Need exact distances or a precise reorder store? Use fp32.
2. Just want to halve memory with negligible recall loss? Use fp16 (or bf16 if the data has a wide dynamic range, e.g. unnormalized embeddings).
3. Want ~4× memory saving and willing to enable reorder? Use sq8 (or sq8_uniform for better SIMD throughput on l2 / ip).
4. Memory-tight and willing to lose more recall before reorder? Use sq4_uniform.
5. High-dim vectors, want strong compression with codebooks? Use pq, or pqfs when the platform supports the SIMD path.
6. Maximum compression (1-bit) and willing to pay reorder cost? Use rabitq, ideally with rabitq_use_fht: true or a tq chain.

For every lossy quantizer above, enabling use_reorder: true with precise_quantization_type: "fp32" is the standard way to recover recall at the cost of extra memory; see the HGraph build-parameter table for the exact behavior.

Where quantization is exposed

Not every index exposes every parameter as an external key. As of today:

• HGraph exposes the richest set: base_quantization_type, precise_quantization_type, use_reorder, base_pq_dim, rabitq_pca_dim, rabitq_bits_per_dim_query, rabitq_bits_per_dim_base, rabitq_bits_per_dim_precise, rabitq_error_rate, rabitq_use_fht, sq4_uniform_trunc_rate, tq_chain (see src/algorithm/hgraph/hgraph.cpp).
• IVF exposes base_quantization_type, base_pq_dim, the common reorder keys, and the RabitQ tuning keys rabitq_pca_dim, rabitq_bits_per_dim_query, rabitq_bits_per_dim_base, rabitq_bits_per_dim_precise, rabitq_version, rabitq_error_rate, and rabitq_use_fht.
• Pyramid exposes base_quantization_type, base_pq_dim, the common reorder keys, and the RabitQ PCA, base/query bit, and FHT keys.
• BruteForce exposes base_quantization_type and the common reorder keys; some tunables (e.g. tq_chain) are wired internally but not exposed as external keys today.

Refer to each index page for its full parameter list.

In this chapter

• FP32 (Baseline)
• Half-Precision (FP16 / BF16)
• Scalar Quantization (SQ4 / SQ8)
• Scalar Uniform (SQ4 / SQ8 Uniform)
• Product Quantization (PQ)
• PQ FastScan
• RaBitQ
• RaBitQ x+y Split
• Transform Quantizer (TQ)

FP32 (Baseline)

fp32 stores every coordinate as a 32-bit IEEE-754 float — the same layout as the input vectors. It is the only fully lossless option in VSAG and serves as the reference baseline that all other quantizers are compared against.

Implementation: src/quantization/fp32_quantizer.cpp, parameter file fp32_quantizer_parameter.cpp.

When to use it

• Reorder / precise store. precise_quantization_type: "fp32" is the default precise store when use_reorder: true; the graph walk uses a cheap base quantizer and the top-K candidates are re-scored exactly against the fp32 copy.
• Reference / ground truth. Building an index with base_quantization_type: "fp32" gives the highest possible recall for that index type and is the standard baseline for benchmarking other quantizers (docs/docs/en/src/resources/eval.md).
• Small datasets where memory is not the bottleneck.
• BruteForce with raw-vector retrieval. SUPPORT_GET_RAW_VECTOR_BY_IDS is only advertised when base_quantization_type is fp32 and the metric allows it (src/algorithm/bruteforce/bruteforce.cpp).

Memory cost

4 × dim bytes per vector for the codes alone. When fp32 is used as a precise store on top of a base quantizer, the per-vector cost is base codes + 4 × dim.

Parameters

fp32 has no quantizer-specific JSON parameters.

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

Training

Not required. fp32 does not set NEED_TRAIN.

Metric compatibility

l2, ip, cosine — all supported with no special handling.

Related pages

• Quantization overview
• HGraph index — see precise_quantization_type
• Memory Management

Half-Precision (FP16 / BF16)

fp16 and bf16 store each coordinate in 16 bits instead of 32, cutting code memory in half with near-lossless accuracy. They have no quantizer-specific JSON parameters; the only difference is the bit layout of the float format itself.

Implementation: src/quantization/scalar_quantization/half_precision_quantizer.cpp with the type traits at half_precision_traits.h. Runnable example: examples/cpp/321_index_fp16_hgraph.cpp.

FP16 vs BF16 at a glance

Practical implications:

• fp16 keeps more mantissa bits — better precision for normalized embeddings whose values lie roughly in [-1, 1]. Standard choice for cosine-normalized vectors.
• bf16 keeps the full fp32 exponent range — safer for raw, un-normalized features (e.g. weighted sums, accumulator-like embeddings). Loses some precision compared to fp16 on values close to zero.

If you do not know which one to pick, start with fp16 for normalized embeddings and bf16 for unnormalized or wide-range data.

When to use it

• Default “drop-in” memory saving on top of an fp32 baseline. Recall loss is typically below 1% on standard benchmarks (SIFT, GIST, Glove, sentence embeddings).
• As a precise reorder store that is half the size of fp32: precise_quantization_type: "fp16" or "bf16" with use_reorder: true.
• High-dim float vectors where 32-bit storage is the bottleneck.

Memory cost

2 × dim bytes per vector for the codes alone.

Parameters

Neither fp16 nor bf16 has quantizer-specific JSON parameters.

{
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 768,
    "index_param": {
        "base_quantization_type": "fp16",
        "max_degree": 32,
        "ef_construction": 300
    }
}

Swap "fp16" for "bf16" to switch formats. The input dtype stays "float32": the quantizer converts on the fly.

Training

Not required. Neither fp16 nor bf16 sets NEED_TRAIN.

Metric compatibility

l2, ip, cosine — all supported. cosine is implemented by normalizing inputs before storing them at 16-bit precision.

When not to use it

• When you also need a memory-aggressive base quantizer such as sq8 or pq — those already pull the storage well below 2 bytes/dim.
• When you need exact distances (use fp32).

Related pages

• Quantization overview
• HGraph index — precise_quantization_type table
• Memory Management

Scalar Quantization (SQ4 / SQ8)

sq8 and sq4 are per-dimension scalar quantizers: each coordinate is mapped from float32 to an 8-bit (sq8) or 4-bit (sq4) integer using a per-dimension [min, max] range learned during training. They share the same implementation, parameterized by bit width, in src/quantization/scalar_quantization/scalar_quantizer.cpp and scalar_quantizer_parameter.h.

For SIMD-friendlier variants with a global [min, max], see Scalar Uniform.

SQ4 vs SQ8 at a glance

The training is per-dimension min/max, so heavy-tailed coordinates can waste code bits. If your data is anisotropic, consider either Scalar Uniform or a Transform Quantizer chain like "rom, sq8_uniform" to rotate first.

Memory cost (codes only)

• sq8: dim bytes per vector.
• sq4: ceil(dim / 2) bytes per vector.

There is also a small per-dimension range table (8 × dim bytes, amortized across all vectors).

Parameters

Neither sq8 nor sq4 has quantizer-specific JSON parameters today (scalar_quantizer_parameter.h:36-58). The bit width is selected by the type string alone.

{
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 128,
    "index_param": {
        "base_quantization_type": "sq8",
        "max_degree": 32,
        "ef_construction": 300,
        "use_reorder": true,
        "precise_quantization_type": "fp32"
    }
}

Replace "sq8" with "sq4" for 4-bit codes.

Training

NEED_TRAIN is set. Training collects per-dimension min / max from a sample of the input vectors. Calling Build(base) trains internally; on indexes that require an explicit Train (some IVF flows), call it before Add. See Build and Train.

Metric compatibility

For sq8 and sq4, l2, ip, cosine are all supported. Distances are computed by decoding the integer codes back to per-dimension scaled floats.

When to choose sq8 vs sq4

• sq8: default memory-saving choice for graph indexes (HGraph, Pyramid) when ~4× memory reduction is the target. Recall loss is small enough that use_reorder is often optional, but enabling it with precise_quantization_type: "fp32" is the safest setup.
• sq4: choose when memory is tight and you can afford a precise reorder store. Almost always pair with use_reorder: true.
• Pick sq*_uniform instead when the data is roughly homogeneous across dimensions; the uniform variants have higher SIMD throughput.
• For heavy-tailed / anisotropic data, prefer a Transform Quantizer chain that rotates before quantization.

Related pages

• Scalar Uniform (SQ4 / SQ8 Uniform)
• Transform Quantizer
• Quantization overview

Local SQ4 / SQ8 (float32 L2, IP and cosine)

HGraph accepts sq4_local and sq8_local as base_quantization_type, or as precise_quantization_type with use_reorder: true. Both support dense float32 L2, IP and cosine. For example, use RaBitQ traversal with local SQ4 reranking:

{
    "dtype": "float32",
    "metric_type": "cosine",
    "dim": 128,
    "index_param": {
        "base_quantization_type": "rabitq",
        "use_reorder": true,
        "precise_quantization_type": "sq4_local",
        "max_degree": 32,
        "ef_construction": 300
    }
}

Replace sq4_local with sq8_local for eight-bit precision. Direct search uses, for example, base_quantization_type: "sq8_local" and use_reorder: false. Existing optional FP32 reranking remains available; local reranking does not add a hidden FP32 store or third reranking stage. The name precise_quantization_type does not guarantee exact distances: both local stores are lossy, and SQ4’s coarser levels can reduce recall substantially. Choose precision and search settings using your own data.

Design and layout

Each vector stores its own FP32 minimum m and FP32 scale s = (max - min) / (2^bits - 1). Offsets 0–3 contain m, offsets 4–7 contain s, and codes start at offset 8. There is no padding or record alignment requirement.

For odd SQ4 dimensions the unused high nibble is zero. Code storage is N * bytes_per_vector, excluding graph, IDs, allocator capacity and optional other stores. Each query computer uses 4 * dim scratch bytes. Cosine encoding additionally uses a temporary 4 * dim normalization buffer.

Encoding rounds (x - m) / s to the nearest integer (half steps round upward) and clamps to [0, 255] or [0, 15]. Constant vectors use zero scale and zero codes. Decode reconstructs m + s * code with fused rounding (and finite endpoint clamping). Unlike sq8 / sq4, ranges are per vector rather than trained per coordinate. Unlike uniform SQ, queries remain FP32.

Metric definitions and normalization

• L2: squared Euclidean distance between the FP32 query and reconstructed database vector. Code-to-code distance reconstructs both operands independently.
• IP: 1 - dot(query, decoded_vector), retaining original magnitudes. Code-to-code uses 1 - dot(decoded_a, decoded_b). Both minimum offsets contribute to the dot product.
• Cosine: the quantizer applies the same Normalize routine as existing ScalarQuantizer to original database vectors before encoding, and to the FP32 query before ADC. Distance is then 1 - dot, as above. Decoded vectors are not renormalized; quantization can change their norm, so results need not lie exactly in [0, 2]. Zero vectors remain zero; their cosine distance to any vector is 1.

HGraph passes the original vectors to these stores; the quantizer owns cosine normalization. The shared FP32 normalization semantics also apply to extreme values: norm overflow may produce zero normalized components, and underflow/denormal handling may preserve tiny components. This feature does not redefine the established normalization policy.

Numeric and training contract

Other input dtypes and transform wrappers around local SQ are rejected. Negative and constant vectors are supported; encoding and query processing reject NaN and infinity. Range calculation uses double intermediates. Extreme finite records use a double-intermediate distance fallback, with reconstructed values clamped to finite FP32 endpoints. Distances outside the FP32 range can be infinite. Tiny ranges may round the FP32 scale to zero and are subject to platform denormal handling. SIMD results agree within floating-point tolerance, not necessarily bit for bit.

Dimensions from 1 to INT_MAX, odd dimensions and unaligned records are supported. Shared kernels cover scalar, SSE, AVX, AVX2, AVX512 and NEON paths; SVE uses the scalar fallback. SSE/AVX reconstruct lanes scalarly with fused rounding before SIMD accumulation so that ADC agrees with the public decoder. Native ARM execution was unavailable for this change’s local validation.

There are no learned shared bounds or extra parameters. Train / ReTrain complete without consuming samples; encoding computes each vector’s metadata. HGraph reports NEED_TRAIN as false when either local type is the base store. HGraph’s normal Build/Train lifecycle still applies.

Persistence and Tune

Existing sq8, sq4, sq8_uniform, defaults and their formats are unchanged.

The local types require readers that support them. Records and quantizer metadata use existing native binary conventions, not a new cross-endian format. Loading validates dimension, metric and record length. HGraph serialization preserves base and precise stores, including RaBitQ plus either local quantizer. Tune can create them from retained raw data or FP32 codes; lossy local codes alone cannot supply a later precision-changing Tune. Existing ignore_reorder, reorder_source and Tune restrictions remain applicable.

No broad recall/throughput benchmark campaign accompanies this change.

Scalar Quantization Uniform (SQ4 / SQ8 Uniform)

sq8_uniform and sq4_uniform are scalar quantizers like sq8 / sq4, except they learn a single global [min, max] range that applies to every dimension. This trade-off — slightly less adaptive per dimension, but a much simpler decode path — unlocks SIMD code that runs significantly faster on l2 and ip distance kernels and keeps the code layout tighter.

Implementation: src/quantization/scalar_quantization/sq8_uniform_quantizer.cpp, src/quantization/scalar_quantization/sq4_uniform_quantizer.cpp.

Why it is fast: distances stay in the integer domain

This is the core reason to prefer sq*_uniform over sq* whenever it applies. Because every dimension shares one (min, max) pair, the affine decode x = min + code · (max - min) / (2^b - 1) has the same scale and offset for every coordinate. That has three consequences in the hot path:

• The query is encoded once with the same global (min, max) into a uint8 (or packed nibble) buffer, in ProcessQueryImpl (src/quantization/scalar_quantization/sq8_uniform_quantizer.cpp:179).
• Each base vector code is never decoded back to fp32. The kernel SQ8UniformComputeCodesIP(uint8_t* q, uint8_t* x, dim) / SQ4UniformComputeCodesIP(...) reads both operands as raw integer codes and does the dot product on uint8 / packed nibble lanes using AVX-512 / AMX (or NEON on ARM), one cache-line at a time. There is no per-element fp dequantization in the inner loop.
• The single shared scale factor and offset are applied once per pair, after the integer reduction, to recover the fp distance. Some metric-specific corrections (a per-vector norm or sum) are also added outside the loop; see the trailing metadata noted in sq8_uniform_quantizer.cpp:200 and the SQ8UniformComputeCodesIPBatch batch kernel.

In the per-dimension sq* quantizers, each coordinate has its own (min_i, max_i) so the kernel either has to multiply by a per-dim scale table inside the loop or decode at least one operand back to fp first. Skipping that work is what makes uniform variants significantly faster at the same recall.

When to use it

• HGraph / IVF / Pyramid hot paths. When the bottleneck is the base-quantizer distance computation, sq8_uniform / sq4_uniform are almost always faster than their non-uniform counterparts at comparable recall.
• Data with similar coordinate ranges across dimensions. Normalized embeddings (cosine), or vectors that have already been rotated (e.g. through a Transform Quantizer chain like "rom, sq8_uniform" or "fht, sq8_uniform") are the ideal inputs.
• As the terminal quantizer of a tq chain. The most common chain is "pca, rom, sq8_uniform", see example 501.

SQ4 uniform vs SQ8 uniform

Parameters

sq8_uniform has no quantizer-specific JSON parameters.

When using HGraph, sq4_uniform_trunc_rate is exposed as a top-level key and mapped into the nested quantization params (src/algorithm/hgraph.cpp:409-416).

{
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 128,
    "index_param": {
        "base_quantization_type": "sq4_uniform",
        "sq4_uniform_trunc_rate": 0.05,
        "max_degree": 32,
        "ef_construction": 300,
        "use_reorder": true,
        "precise_quantization_type": "fp32"
    }
}

Set "base_quantization_type": "sq8_uniform" and drop the trunc_rate key for the 8-bit variant.

Training

NEED_TRAIN is set. Training estimates one global [min, max] across all dimensions (with optional truncation for sq4_uniform). Build will perform training internally.

Metric compatibility

l2, ip, cosine — all supported. cosine normalizes before quantizing, which is also what makes uniform scaling close to optimal for that metric.

Choosing between uniform and non-uniform

• Data is normalized (cosine or pre-normalized l2) → uniform.
• Data has very heterogeneous per-dimension ranges (e.g. mixed feature blocks) → start with non-uniform sq*, or use uniform behind a rotation transformer ("rom, sq*_uniform").
• Throughput matters more than the last bit of recall → uniform.

Related pages

• Scalar Quantization (SQ4 / SQ8)
• Transform Quantizer
• Quantization overview

Product Quantization (PQ)

Product Quantization splits a vector into pq_dim equal-sized subvectors and quantizes each one independently against a small learned codebook of 2^pq_bits centroids. The stored code is then pq_dim × pq_bits bits per vector — orders of magnitude smaller than fp32. Distance computations use precomputed lookup tables (LUT) per query.

Implementation: src/quantization/product_quantization/product_quantizer.cpp, parameter file product_quantizer_parameter.cpp.

When to use it

• High-dim float vectors (≥ 256 dim) where sq8 is still too large.
• Memory-tight, accuracy-acceptable workloads where ~16× compression vs fp32 is required.
• Combined with use_reorder: true and a small fp16/fp32 precise store, PQ is the standard “compressed graph index” recipe at large scale.

For wider SIMD throughput at pq_bits = 4, see PQ FastScan.

Memory cost (codes only)

ceil(pq_dim × pq_bits / 8) bytes per vector for the codes, plus a small codebook stored once (pq_dim × 2^pq_bits × subspace_dim × 4 bytes). For typical settings (pq_dim = 32, pq_bits = 8, dim = 128):

• code size = 32 × 8 / 8 = 32 bytes per vector (vs 128 × 4 = 512 for fp32 → 16× smaller).

Parameters

On HGraph these are exposed as the top-level keys base_pq_dim and pq_bits (src/algorithm/hgraph.cpp:465-472).

{
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 128,
    "index_param": {
        "base_quantization_type": "pq",
        "base_pq_dim": 32,
        "max_degree": 32,
        "ef_construction": 300,
        "use_reorder": true,
        "precise_quantization_type": "fp16"
    }
}

Training

NEED_TRAIN is set. Training runs k-means per subspace to learn the 2^pq_bits centroids; this is typically the most expensive training step of any built-in quantizer. Use a training sample of at least 256 × 2^pq_bits vectors per subspace for stable codebooks; Build(base) samples from the input automatically.

Metric compatibility

l2, ip, cosine — all supported. Query-time distance is computed via a per-subspace LUT: for l2 it is squared L2 between the query subvector and each centroid; for ip it is the dot product. Cosine reduces to ip on pre-normalized vectors.

Tips

• pq_dim should divide dim evenly. Common ratios are dim/4 or dim/8.
• Very small pq_dim (e.g. dim/16) produces very compact codes but loses recall fast; combine with reorder.
• For anisotropic data, a rotation transformer in front improves PQ recall noticeably: use Transform Quantizer with a chain like "rom, pq".

Related pages

• PQ FastScan
• Transform Quantizer
• HGraph index
• Quantization overview

PQ FastScan

pqfs is a SIMD-accelerated variant of Product Quantization that fixes pq_bits = 4 and uses a memory layout designed for the AVX-2 / AVX-512 “FastScan” lookup-table kernel. At the cost of being 4-bit only, it delivers significantly higher distance-computation throughput.

Implementation: src/quantization/product_quantization/pq_fastscan_quantizer.cpp, parameter file pq_fastscan_quantizer_parameter.cpp.

When to use it

• The platform has AVX-2 (and ideally AVX-512); the FastScan kernel is the main reason to choose pqfs over pq.
• Search throughput, not just memory, matters.
• 4-bit subspace codebooks (16 centroids per subvector) are sufficient for your recall target — typically yes when combined with reorder.

If your platform does not advertise the required SIMD width, fall back to plain pq.

Memory cost (codes only)

ceil(pq_dim / 2) = (pq_dim + 1) / 2 bytes per vector — both even and odd pq_dim are supported (src/quantization/product_quantization/pq_fastscan_quantizer.cpp:41). Codebooks: pq_dim × 16 × subspace_dim × 4 bytes — significantly smaller than 8-bit pq because the codebook has only 16 centroids per subspace.

Parameters

Exposed on HGraph as base_pq_dim (src/algorithm/hgraph.cpp:465-472).

{
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 128,
    "index_param": {
        "base_quantization_type": "pqfs",
        "base_pq_dim": 32,
        "max_degree": 32,
        "ef_construction": 300,
        "use_reorder": true,
        "precise_quantization_type": "fp16"
    }
}

Training

NEED_TRAIN is set. Trains 16-centroid codebooks per subspace; cheaper than the 256-centroid training in pq.

Metric compatibility

l2, ip, cosine — same coverage as pq. The LUT layout is metric- specific but transparently handled by the quantizer.

Tips

• pq_dim should be a multiple of the SIMD-batch width the kernel expects (the implementation uses 32 internally on AVX-512). When in doubt, choose pq_dim ∈ {32, 64, 96, 128}.
• The benefit over pq is throughput at the same recall, not memory (4-bit codes are inherently smaller, but pq with pq_bits = 4 would match).
• For maximum recall recovery, pair with use_reorder: true and an fp16 or fp32 precise store.

Related pages

• Product Quantization (PQ)
• HGraph index
• Transform Quantizer
• Quantization overview

RaBitQ

rabitq is VSAG’s binary / low-bit quantizer. In its default mode each coordinate is encoded with 1 bit, giving the highest compression ratio of any built-in quantizer. On HGraph, IVF, and Pyramid, an x+y split mode stores low-bit base codes as x filter bits plus y supplement bits, so graph traversal or IVF bucket scanning can use only the filter code and re-ranking can fetch only the supplement bits it needs.

Implementation: src/quantization/rabitq_quantization/rabitq_quantizer.cpp, parameter file rabitq_quantizer_parameter.cpp. For the complete split layout, lower-bound formula, and IO modes, see RaBitQ x+y Split.

When to use it

• Maximum compression. 1-bit codes are the smallest possible storage for dense vectors.
• High-dim embeddings where rotation + binarization preserves enough geometry for nearest-neighbor search.
• Combined with a precise reorder store (fp16 / fp32) — the standard recipe is “RaBitQ + reorder”, because the binary distance is noisy on its own.

For best accuracy, also enable rabitq_use_fht: true or wrap with a Transform Quantizer chain such as "pca, rom, rabitq".

Memory cost (codes only)

• rabitq_bits_per_dim_base = 1: ceil(dim / 8) bytes per vector. With dim = 768 that is 96 bytes (vs 3072 for fp32 → 32× smaller).
• rabitq_bits_per_dim_base = x plus rabitq_bits_per_dim_precise = y on HGraph, IVF, or Pyramid: split mode stores roughly (x + y) * dim / 8 bytes per vector for the RaBitQ code bytes. For example, 3+5 is about dim bytes per vector.

Parameters

Multi-bit RaBitQ uses an LVQ initialization followed by fixed-round coordinate adjustment when fast_encode_rabitq is enabled. This reduces code selection from approximately O(2^B * dim * log(dim)) to O(rounds * dim) while keeping the existing code layout and query estimator. The implementation follows the CAQ component of SAQ; use the exact fallback when measuring the quality/speed trade-off on a new dataset. These build-only settings do not affect index loading compatibility. VSAG uses a clean-room implementation and does not depend on the Apache-2.0 licensed SAQ reference repository.

Index pages expose RaBitQ settings as top-level index_param keys: HGraph exposes rabitq_pca_dim, rabitq_bits_per_dim_query, rabitq_bits_per_dim_base, rabitq_bits_per_dim_precise, rabitq_error_rate, and rabitq_use_fht; IVF exposes rabitq_pca_dim, rabitq_bits_per_dim_query, rabitq_bits_per_dim_base, rabitq_bits_per_dim_precise, rabitq_version, rabitq_error_rate, and rabitq_use_fht; Pyramid exposes the PCA, base/query bit, and FHT keys for its base quantizer. The rabitq_use_fht key is an index-level alias for the quantizer’s internal use_fht key and is rewritten by the index layer. fast_encode_rabitq and fast_encode_rabitq_rounds are available on HGraph, IVF, and Pyramid and are propagated to both base and precise RaBitQ quantizers.

For a normal first HGraph or Pyramid build with split RaBitQ and fast_encode_rabitq=true, the index first encodes all vectors into one unsigned-byte scalar code per dimension, together with the standard RaBitQ metadata and a separate 8-byte code sum per vector. It waits for the encoding phase before starting graph tasks. Those tasks use scalar SIMD kernels for code-code distances; the raw inner-product kernels are independent of the configured x+y bit count, while the quantizer still applies the matching quantization range and center. After construction, the scalar codes are packed once into bit planes and written to the persistent filter and supplement stores without rerunning PCA, ROM/FHT, or RaBitQ quantization. The temporary scalar records and code sums are released before Build returns. For an 8-bit total code the scalar and packed payloads have the same size; lower total bit counts trade extra build memory for faster graph-distance evaluation.

Pyramid also uses the scalar SIMD build path described above for ordinary initial Build calls (NSW and ODescent), including 3+5 split configurations. Construction uses symmetric distances from the full x+y-bit codes, then packs filter/supplement records once and releases temporary storage. Setting fast_encode_rabitq=false selects the existing build path. Builds that use an imported Build Cache and subsequent Add calls do not enable this temporary build mode. Pyramid encodes in parallel when storage is preallocated and the IO supports it, and sequentially otherwise; both cases use scalar SIMD graph distances. Pyramid does not require the HGraph-only rabitq_fused_datacell option.

{
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 768,
    "index_param": {
        "base_quantization_type": "rabitq",
        "rabitq_use_fht": true,
        "rabitq_pca_dim": 0,
        "rabitq_bits_per_dim_base": 1,
        "rabitq_bits_per_dim_query": 32,
        "max_degree": 32,
        "ef_construction": 300,
        "use_reorder": true,
        "precise_quantization_type": "fp32"
    }
}

Swap to the higher-accuracy x+y split mode by setting both base and precise quantization to RaBitQ and providing rabitq_bits_per_dim_precise. HGraph, IVF, and Pyramid then automatically select the split datacell. In the example below, filtering uses x = 3 filter bits and reorder reads only y = 5 supplement bits:

{
    "base_quantization_type": "rabitq",
    "precise_quantization_type": "rabitq",
    "rabitq_bits_per_dim_base": 3,
    "rabitq_bits_per_dim_precise": 5,
    "rabitq_use_fht": true
}

Training

NEED_TRAIN is set. Training learns the rotation and per-dimension statistics that make the 1-bit encoding well-balanced. The optional FHT rotation is fixed (not learned), so it adds no extra training cost; PCA preprocessing (when pca_dim > 0) trains a projection matrix.

Metric compatibility

l2, ip, cosine — all supported. The binary distance kernel is a popcount over XORed code words; for ip / cosine the implementation also tracks a residual norm so the inner-product estimate is unbiased.

Tips

• Always enable reorder unless you have validated that 1-bit recall is acceptable on your data. use_reorder: true + precise_quantization_type: "fp32" is the safe default.
• Rotate first. For un-normalized data, set rabitq_use_fht: true or use a tq chain that includes rom / fht.
• Split mode for accuracy. HGraph/IVF/Pyramid x+y split keeps an x-bit fast path for filtering and adds y supplement bits for re-ranking; expect significantly higher recall than pure 1-bit when using more total bits.

Related pages

• Transform Quantizer
• HGraph index
• RaBitQ x+y Split
• Quantization overview

RaBitQ x+y Split

RaBitQ x+y split is an HGraph, IVF, and Pyramid storage and search mode for low-bit base codes. Each vector is divided into two records:

• x filter bits are read during graph traversal or IVF bucket scanning.
• y supplement bits are fetched only for candidates that reach reorder.
• The final reorder distance uses all x+y bits.

This layout keeps the traversal record small while retaining a higher-precision RaBitQ distance for final ranking. It also allows the filter record to stay in memory while the colder supplement record is stored on disk.

Enable split mode

HGraph, IVF, and Pyramid select split mode when both quantization types are rabitq and rabitq_bits_per_dim_precise is present:

{
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 960,
    "index_param": {
        "base_quantization_type": "rabitq",
        "precise_quantization_type": "rabitq",
        "use_reorder": true,
        "rabitq_bits_per_dim_query": 32,
        "rabitq_bits_per_dim_base": 3,
        "rabitq_bits_per_dim_precise": 5,
        "rabitq_error_rate": 1.9,
        "max_degree": 64,
        "ef_construction": 400
    }
}

The relevant parameters are:

The constraints are:

1 <= x <= 8
1 <= y <= 8
x + y <= 8

If rabitq_bits_per_dim_precise is omitted, HGraph, IVF, and Pyramid use the standard RaBitQ path instead of split storage.

HGraph fused in-memory layout

For HGraph only, set rabitq_fused_datacell to true to store each bottom-layer node’s neighbors, cluster id, label, x-bit code, and y-bit supplement in one cache-line-aligned record. Pyramid uses ordinary split storage; rabitq_fused_datacell is not a Pyramid parameter. The specialized HGraph search loop reads the record directly and prefetches graph links and quantized codes together. The codec uses 16 reproducibly trained residual clusters.

By default, fused HGraph trains the base RaBitQ quantizer and fused KMeans codec on at most 65,536 vectors. When train_sample_count is smaller than the dataset, it selects that many vectors using fixed-seed uniform reservoir sampling. Increasing the value can improve cluster-centroid quality at the cost of build time and temporary training memory; set it to at least the dataset size to train on all vectors.

This option creates an incrementally mutable in-memory index. After Build or Deserialize, it supports Add, mark remove, vector/id/attribute/extra-info updates, search (including filters, iterators, range search, and concurrent queries), distance-by-id, memory statistics, and serialization/deserialization. Force remove, merge, tune, clone, model export, and build-cache import/export remain unsupported. Build and Deserialize leave the index mutable and retain the search and per-node locks. Call SetImmutable explicitly when no more mutations are needed; this terminal transition removes those locks from the search path, and later mutations are rejected.

Each record starts with a 4-byte neighbor count followed by plain InnerIdType neighbor IDs. There is no node version and no version encoding in neighbor IDs. Cluster id, aligned external label, filter code, and supplement follow; the record stride remains rounded up to a 64-byte boundary. Storage can grow during Build and later Add operations.

The optimized build uses temporary SQ8 scalar codes for symmetric base-to-base graph construction, then discards them. The completed index keeps only the fused RaBitQ records. Post-build Add decodes fused records on demand for pairwise graph updates, so it does not retain an SQ8 or raw-vector copy; batch adds are preferable when insertion throughput matters.

The fused layout is opt-in and has stricter constraints than ordinary split storage:

• 1 <= x <= 4, y >= 1, and x + y <= 8.
• The metric must be L2 or inner product.
• The graph, filter codes, and supplement codes must all use memory IO.
• MCI, deduplicate_storage, removal metadata, reverse edges, and force remove must be disabled.
• PCA is not supported; omit rabitq_pca_dim or set it to 0.
• The legacy v0.14 serialization format is not supported.
• The fused slab wire format is versioned independently. The current format intentionally rejects earlier development formats that contained node versions and remove flags.

Indexes created without this option keep their existing layout, behavior, and serialization format.

Enable the filter/lower-bound search path with:

{
    "hgraph": {
        "ef_search": 200,
        "parallelism": 4,
        "rabitq_one_bit_search": true,
        "rabitq_error_rate": 1.9
    }
}

For Pyramid, put the equivalent search controls under pyramid:

{
    "pyramid": {
        "ef_search": 200,
        "rabitq_one_bit_search": true,
        "rabitq_error_rate": 1.9
    }
}

The external search key is named rabitq_one_bit_search, but on a split index it uses all x filter bits configured by rabitq_bits_per_dim_base. hgraph.rabitq_error_rate and pyramid.rabitq_error_rate override the index default for their respective searches without requiring a rebuild. Native fused HGraph records store the geometric error scale before this multiplier is applied. HNSW-compatible fused 1+7 records retain metadata scaled by the canonical default and apply an override as a ratio at query time.

IVF bucket scans use the configured x filter bits automatically; no rabitq_one_bit_search switch is needed. The ivf.factor parameter controls how many filter-stage candidates (factor * topk) proceed to supplement reranking.

Search pipeline

The split search path has four stages:

1. The query is transformed and normalized once. Residual IVF builds one shared HighAcc lookup table from the original transformed query.
2. IVF bucket scanning reads only the packed x-bit filter record and emits a distance estimate plus the reusable quantized filter inner product.
3. IVF retains factor * topk candidates by filter distance. The candidate heap carries the source bucket, offset, and version needed to validate the saved inner product under concurrent updates.
4. Reranking reads only the y-bit supplement on the valid fast path and combines it with the saved filter contribution. Packed x bits are reread only by the correctness fallback for an invalid or stale candidate.

Encoding and bit planes

Let:

d       = transformed dimension
x       = filter bits per dimension
y       = supplement bits per dimension
B       = x + y
P       = ceil(d / 8), bytes in one bit plane
q_i     = transformed and normalized query coordinate
u_i     = unsigned B-bit base code, 0 <= u_i < 2^B

The centered full code is:

c_B = (2^B - 1) / 2
z_i = u_i - c_B
N_B = sqrt(sum_i z_i^2)

PackIntoPlanes stores each logical bit of u_i in a separate bit plane. The split is defined by:

f_i = floor(u_i / 2^y)    # top x bits
s_i = u_i mod 2^y         # low y bits
u_i = 2^y * f_i + s_i

The physical order keeps the most significant filter planes contiguous:

filter record:     logical B-1, B-2, ..., B-x
supplement record: logical 0, 1, ..., y-1

This order lets traversal scan exactly x * P plane bytes and lets reorder fetch exactly y * P additional plane bytes, excluding metadata and alignment.

Datacell layout

RaBitQSplitDataCell owns two RaBitQSplitCodeStorage instances.

Filter record

The filter record in x_bit_cell_ contains:

x high bit planes
base norm
filter-code norm when x > 1
optional MRQ residual norm
optional raw norm for IP/cosine
lower-bound error
filter approximation error

For one vector, its plane payload is:

FilterPlanesSize = x * ceil(d / 8)

The filter record is the hot traversal record. Graph search and prefetch do not need the supplement record while the x-bit estimate is valid.

Supplement record

The supplement record in supplement_cell_ contains:

y low bit planes
full-code norm
full-code approximation error
remaining metadata required by the selected metric and transforms

Its plane payload is:

SupplementPlanesSize = y * ceil(d / 8)

The complete code payload is approximately (x+y) * d / 8 bytes per vector, plus aligned norms, errors, and optional transform metadata.

X-bit filter estimate and lower bound

The filter code for coordinate i is f_i in [0, 2^x - 1]. Define:

c_x   = (2^x - 1) / 2
N_x   = sqrt(sum_i (f_i - c_x)^2)
S_x   = sum_i q_i * f_i
Q_sum = sum_i q_i
rho_x = (S_x - c_x * Q_sum) / N_x

During index construction, RaBitQ stores the absolute filter approximation error E_x and the geometric error scale:

E_safe    = clamp(abs(E_x), 1e-5, 1)
epsilon_x = sqrt(max(0, 1 - E_safe^2) / max(1, d - 1))

The corrected filter inner-product estimate is:

rho_hat_x = rho_x / abs(E_x)

For L2, with base norm N_o and query norm N_q, the x-bit distance and lower bound are:

D_x = N_o^2 + N_q^2 - 2 * N_o * N_q * rho_hat_x

LB = D_x
     - 2 * N_o * N_q * rabitq_error_rate * epsilon_x / abs(E_x)

The implementation subtracts a small floating-point guard from LB. IP and cosine apply the corresponding metric conversion to the error term.

The lower bound is used only to reject candidates safely. D_x remains the traversal estimate, while the final ranking uses the x+y distance.

IVF 1-bit, 2-bit, and 3-bit 32-vector FastScan layout

When IVF split storage uses x from 1 through 3, RaBitQSplitBucketDataCell packages each bucket in groups of 32 candidates. These bucket-local packed blocks are the only persistent filter-code layout and contain the SIMD-oriented filter planes plus compact metadata. Single-lane x bits are unpacked from the block only for correctness fallback or full-code access by ID. Supplement reranking normally reads only the separate y-bit record.

Let G = ceil(d / 8) * 2 be the number of four-dimensional groups in one bitplane. Each group stores one four-bit mask per candidate. For every group, the 32 masks are transposed into 16 bytes. The low nibbles represent candidates 0..15, the high nibbles represent candidates 16..31, and both halves use the lane order 0, 8, 1, 9, ..., 7, 15. Multiple bitplanes remain separate and contiguous in plane-major order.

For x = 1, each group has the 16-entry subset-sum table:

LUT_g[m] = sum(q_(4g+j) for j in [0, 3] when bit_j(m) is set)

For x = 2 or x = 3, let bitplane zero be the most significant plane. The centered lookup table is:

weight(x, p) = 2^(x - p - 2)
LUT_(p,g)[m] = weight(x, p) * sum((2 * bit_j(m) - 1) * q_(4g+j))

The plane weights are {1, 0.5} for two bits and {2, 1, 0.5} for three bits. Coordinates beyond d are zero.

One-bit and two-bit scans use one query-wide unsigned-byte quantizer. Three-bit scans quantize each plane independently, preventing the low-weight plane from losing effective precision to the four-times-wider range of the high plane:

delta[p] = (v_max[p] - v_min[p]) / 255
plane_sum[p] ~= G * v_min[p] + delta[p] * sum LUT_u8[p][code]
centered_ip ~= plane_sum[0] + plane_sum[1] + plane_sum[2]

The three-bit scanner invokes PQFastScanLookUp32 once for each contiguous plane. This keeps the same 3 * G total shuffle groups and packed-code size as a single combined scan, while allowing separate dequantization scales.

For one bit, the lookup sum is converted to the normalized binary inner product with sum(q) and sqrt(d). For two and three bits, it is already the centered inner product and is divided by the stored filter-code norm. All paths then use the stored RaBitQ norm and error metadata to recover the filter-stage distance.

The packed filter planes are followed by the metadata for all 32 candidates. A final bucket block with fewer than 32 vectors is zero-padded, while the scanner returns only valid candidates. Runtime dispatch selects generic, SSE, AVX2, or AVX-512 code. The dequantized byte-LUT result is saved as S_x and reused in the final x+y estimate, so filtering and reranking share the same LUT quantization error. Wider filter widths continue to use the bit-plane batch paths.

Example configurations are:

{
    "rabitq_bits_per_dim_base": 1,
    "rabitq_bits_per_dim_precise": 7,
    "rabitq_bits_per_dim_query": 32
}

{
    "rabitq_bits_per_dim_base": 2,
    "rabitq_bits_per_dim_precise": 6,
    "rabitq_bits_per_dim_query": 32
}

{
    "rabitq_bits_per_dim_base": 3,
    "rabitq_bits_per_dim_precise": 5,
    "rabitq_bits_per_dim_query": 32
}

GIST1M comparison

The following results compare traditional 8-bit IVF RaBitQ with the split layouts on gist-960-euclidean.hdf5 (1,000,000 base vectors, 960 dimensions, L2). The index used 1,024 buckets, 100,000 training samples, 16 build threads, and rabitq_bits_per_dim_query = 32. Search used one thread, 32 scanned buckets, factor = 10, top-10, and 5,000 measured queries. The split search results include the 32-vector FastScan layout described above.

These numbers are a single-machine comparison rather than a universal performance guarantee. Split storage spends more time building two code streams and keeps a bucket-local FastScan copy in memory. In return, its filter scan avoids reading the full 8-bit code for every candidate. On this workload, 2+6 provides the closest recall to traditional 8-bit RaBitQ while improving search throughput by about 4.2 times; 1+7 maximizes throughput with a larger recall trade-off.

Query lookup table and SIMD

For x = 2 and x = 3, the query computer builds a FastScan-style byte lookup table. Each table row corresponds to eight query coordinates and has 256 entries:

LUT[block][byte_value]
    = sum of q_i for the set bits in byte_value within that 8-D block

Each filter plane then contributes one lookup per byte instead of decoding eight coordinates separately. Binary weights combine the x planes into S_x.

The AVX2 and AVX512 kernels gather multiple lookup entries at once and also provide a batch-of-four path. The scalar implementation is kept as the portable fallback. The relevant entry points are:

• RaBitQFloatMultiBitIPByLookup
• RaBitQFloatMultiBitIPBatch4ByLookup
• RaBitQFloatBuildByteIPLookupTable

An x-bit width outside the specialized set remains supported through the generic bit-plane computation path.

Reorder scans only y supplement bits

The full unsigned code satisfies:

sum_i q_i * u_i
    = 2^y * sum_i q_i * f_i
      + sum_i q_i * s_i

For x >= 2, the dedicated fused HGraph search/reorder path carries the exact x-bit filter inner product from traversal to reorder. It consumes the hint while reading codes directly from the node record, so full rerank computes only the second term from the y supplement planes. For L2 with an x-bit lookup filter, HGraph, IVF, and Pyramid pass the previously computed filter distance to reorder as a hint. ComputeDistWithSplitCodeAndFilterDist recovers the first term from that hint and computes only the second term from the y supplement planes:

full contribution = shifted filter contribution + supplement contribution

Thus fused 2+y, 3+y, and 4+y indexes reuse the exact x-bit filter inner product and scan only the y supplement planes for each reranked candidate. The richer filter-IP/full-distance candidate record is private to HGraph’s fused search path; generic HGraph searchers, Pyramid, and ReorderInterface retain the original distance/id candidate protocol. The fused 1+y traversal uses a four-bit query bit-plane and popcount approximation; precise reranking recomputes its exact one-bit contribution because the approximate value is not an exact full-distance hint. If a usable hint is unavailable, the code computes the same final distance directly from both split records.

Memory, disk, and hybrid IO

Both records use the base IO type unless a separate supplement IO type is configured.

Both records in memory

{
    "base_io_type": "block_memory_io"
}

Both records on disk

{
    "base_io_type": "async_io",
    "base_file_path": "/data/hgraph_rabitq_split"
}

VSAG creates separate backing paths for the filter and supplement records.

Filter in memory, supplement on disk

{
    "base_io_type": "block_memory_io",
    "base_supplement_io_type": "async_io",
    "base_file_path": "/data/hgraph_rabitq_split"
}

The supported mixed-IO combination keeps x_bit_cell_ in block memory and places supplement_cell_ in async IO. During batched reorder, the filter record is read by direct pointer while MultiRead fetches only supplement records. base_supplement_file_path may be set explicitly; otherwise VSAG derives a supplement path from base_file_path.

Serialization and loading

Use the normal index-level serialization API. Applications do not need to persist the two records independently.

std::ofstream out("/path/to/index.bin", std::ios::binary);
auto serialized = index->Serialize(out);

auto loaded = vsag::Factory::CreateIndex("hgraph", index_params).value();
std::ifstream in("/path/to/index.bin", std::ios::binary);
auto deserialized = loaded->Deserialize(in);

The split datacell serializes, in order:

1. Base datacell state and supplement IO type.
2. Filter storage.
3. Supplement storage.
4. RaBitQ quantizer state.

Create the destination index with parameters compatible with the serialized index, especially dim, metric_type, x/y bit widths, and query bits. Changing an encoded parameter requires rebuilding the index. Tuning only the search-time hgraph.rabitq_error_rate or pyramid.rabitq_error_rate does not.

For a fused index, the codec model is serialized with the split datacell and the per-node codes are serialized once as part of the bottom-graph slab. Ordinary and streaming round trips preserve this layout without creating a second count-scaled copy of the split codes.

Implementation map

Operational notes

• Split storage is currently available on HGraph, IVF, and Pyramid and requires fp32 query codes. Pyramid enables the one-bit split search path by default for split indexes; pass rabitq_one_bit_search: false under pyramid to force the standard search path.
• l2, ip, and cosine are supported. For x >= 2, the canonical ordinary split and fused HGraph paths directly reuse the exact filter inner product for L2 and inner product. Other cases safely compute the full split distance.
• The fused datacell supports only L2 and inner product and only the in-memory configuration described above.
• Fused HGraph remains mutable after Build and deserialize. It supports post-build Add, mark remove, and vector/id/attribute/extra-info updates, but not force remove. Call SetImmutable explicitly for the lock-free read-only search path.
• With support_duplicate: true, duplicate build probes and alias-expanding queries use the canonical HGraph searcher; the fused slab remains the code and graph storage.
• Keep use_reorder: true unless x-bit traversal accuracy alone has been validated for the dataset.
• Changing x, y, metric, or transform parameters requires rebuilding the index. A search-time hgraph.rabitq_error_rate or pyramid.rabitq_error_rate override does not.
• Use RaBitQ for the general quantizer description and HGraph and Pyramid for the complete index parameter tables.

Quantization Transform

The Transform Quantizer (base_quantization_type: "tq") chains one or more vector transformations in front of a final quantizer. Transformations reshape vectors so a downstream quantizer can encode them more accurately or compactly — for example, rotate vectors so their energy is spread across dimensions (RaBitQ / SQ benefit greatly), or reduce dimensionality with PCA before storing them.

Runnable example: examples/cpp/501_quantization_transform.cpp.

Why a transform layer

A pure quantizer compresses vectors directly. With low-bit quantizers (e.g. sq4, sq*_uniform, rabitq) accuracy depends heavily on the distribution of vector coordinates: heavy-tailed or anisotropic dimensions waste code bits. A transform layer mitigates this:

• Random rotations (rom, fht) decorrelate coordinates so a uniform/scalar quantizer works better on each axis.
• PCA (pca) reduces dimensions while keeping most of the variance — code size shrinks proportionally.
• MRLE (mrle) is a metric-recoverable low-rank encoding tailored to L2/IP search.

The transform output then feeds a standard quantizer (fp32, sq8, sq8_uniform, rabitq, …), which actually stores the codes. The whole chain is referred to as tq (Transform Quantizer).

Quick start

tq is exposed as a public, externally configurable quantization type by HGraph and Pyramid. Both map tq_chain and dimension parameters into base_codes.quantization_params. The MRLE + RaBitQ x+y split combination is available in both indexes and automatically reorders from the base split datacell. IVF, BruteForce and WARP do not currently expose tq_chain through their external parameter mapping.

std::string params = R"({
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 128,
    "index_param": {
        "base_quantization_type": "tq",
        "tq_chain": "pca, rom, sq8_uniform",
        "rabitq_pca_dim": 64,
        "max_degree": 32,
        "ef_construction": 300,
        "use_reorder": true,
        "precise_quantization_type": "fp32"
    }
})";

vsag::Resource resource(vsag::Engine::CreateDefaultAllocator(), nullptr);
vsag::Engine engine(&resource);
auto index = engine.CreateIndex("hgraph", params).value();
index->Build(base);
auto result = index->KnnSearch(query, topk, search_params).value();

In the example above, base vectors are first projected from 128 to 64 dimensions (pca), randomly rotated (rom), then quantized with sq8_uniform. Reordering is enabled, so HGraph keeps an fp32 precise copy and re-ranks the top candidates returned by the graph search (include/vsag/index.h; see Memory Management for the storage implications).

tq_chain syntax

tq_chain is a comma-separated string: one or more transformer names followed by exactly one final quantizer name. Whitespace around tokens is trimmed (src/quantization/transform_quantization/transform_quantizer_parameter.cpp:53-74).

"<transform1>, <transform2>, ..., <quantizer>"

Examples:

Constraints (transform_quantizer_parameter.cpp:33-45):

• The chain must contain at least one transformer + one quantizer (length ≥ 2). An empty or single-token chain raises INVALID_ARGUMENT.
• The last token must be a quantizer that the TQ flatten path can dispatch: one of fp32, sq8, sq8_uniform, sq4, sq4_uniform, bf16, fp16, pq, pqfs, rabitq (src/datacell/flatten_interface.cpp:126-164). TransformQuantizerParameter parses a slightly wider set of names (it also accepts sparse, int8, tq), but the flatten factory does not have a dispatch branch for int8/tq and explicitly rejects sparse when is_transform_quantizer is true (src/datacell/flatten_interface.cpp:166), so using any of those three as the terminal quantizer fails at index construction with an “unsupported quantization type” error.
• RaBitQ x+y split storage supports TQ only for the exact chain "mrle, rabitq". The split datacell reuses the terminal RaBitQ encoder and keeps RaBitQ internal FHT/ROM rotation behavior unchanged. Other transformed split chains are rejected.
• Any unrecognized transformer name raises INVALID_ARGUMENT: invalid transformer name (transform_quantizer.h:225-227).

Supported transformers

The factory at src/quantization/transform_quantization/transform_quantizer.h:192-227 recognizes four transformer names today:

Notes:

• mrle placement is enforced at transform_quantizer.h:155-159 and mrle_dim ≤ input_dim at transform_quantizer.h:217-220.
• Other strings declared in headers (residual, normalize) are not wired into the factory and will be rejected.

Transformer parameters

The transformer JSON is read by VectorTransformerParameter::FromJson (src/impl/transform/vector_transformer_parameter.cpp:22-35):

HGraph external mapping

When using HGraph, top-level shortcuts are mapped into the nested quantizer params:

• tq_chain → base_codes.quantization_params.tq_chain
• rabitq_pca_dim → base_codes.quantization_params.pca_dim
• mrle_dim → base_codes.quantization_params.mrle_dim

The name rabitq_pca_dim predates Transform Quantizer; when the chain includes pca, it drives the pca transformer’s output dim (it is not RaBitQ-specific). When the chain ends in rabitq without pca, the same key configures RaBitQ’s own PCA preprocessing (src/quantization/rabitq_quantization/rabitq_quantizer_parameter.cpp:30).

mrle_dim accepts an integer in [0, dim]; 0 means the input dimension. It has an effect when tq_chain includes mrle, which must remain the first transform in the chain.

Reordering and the precise codes store

Transform chains lose some information by design (rotation is lossless, but pca / sq*_uniform / rabitq are not). Combining tq with reorder — keep a precise (typically fp32) copy of every vector and re-rank the top candidates — restores accuracy with a modest memory cost:

• use_reorder: true makes HGraph keep a second flatten store, the precise codes store (src/algorithm/hgraph.cpp:76-79).
• precise_quantization_type selects its quantizer (fp32 default; can be fp16 / bf16 / sq8 if you want to trade memory for accuracy).
• At search time the graph walk uses the cheap tq base codes, then the top-K are re-scored against the precise codes (hgraph.cpp:978-981 and surrounding sites).

use_reorder and precise_quantization_type are not specific to tq — they also apply when base_quantization_type is sq8, pq, rabitq, etc. See the table in HGraph index for the full per-index parameter list.

Choosing a chain

A pragmatic rule of thumb:

Always benchmark on your own data — the right tradeoff between tq aggressiveness and use_reorder depends on dataset distribution, target recall, and memory budget.

Compatibility and merge

Two tq configurations are considered compatible only when the chain length, every transformer name, and the final quantizer all match (src/quantization/transform_quantization/transform_quantizer_parameter.cpp:99-117). This matters for serialization round-trips and for any future merge / clone operations across indexes — keep the chain string stable across builds you intend to combine.

Chain string equality is necessary but not sufficient. The tq_chain token list does not encode transformer parameters such as pca_dim / mrle_dim (read as separate sibling JSON keys at src/quantization/transform_quantization/transform_quantizer.h:200-216) or the internal parameters of the terminal quantizer (e.g. pq subspace count, rabitq rotation seed). These parameters change the effective code dimension and layout, so for two builds to be practically merge-/clone-compatible you must keep the entire transform + quantizer parameter set consistent, not just the chain string.

Related pages

• HGraph index — parameter reference for base_quantization_type, use_reorder, precise_quantization_type.
• Memory Management — memory cost of base + precise stores.

Code Structure

This page gives a quick tour of the VSAG repository layout.

Top-Level Directories

Core Subsystems (inside src/)

• index: concrete index implementations (HGraph, IVF, Pyramid, SINDI, and others).
• quantization: FP32 / FP16 / BF16 / SQ4 / SQ8 / PQ quantizers with SIMD dispatch.
• graph: shared graph data structures used by HGraph and other graph-based indexes.
• storage: binary/reader sets, streaming serialization.
• allocator / thread pool: user-pluggable resource management.
• simd: cascaded SIMD dispatch for x86_64 and AArch64.

Naming Conventions

• Public API: vsag namespace, in include/vsag/.
• Implementation: src/, same namespace unless the file explicitly needs otherwise.
• File extension: .cpp (not .cc).

Build Artifacts

make debug / make release / make dev produce build trees:

• build-debug/
• build-release/
• build-dev/

Each contains the test binaries, example executables, and libraries.

C++ Coding Guide

VSAG follows the Google C++ Style Guide with project-specific formatting, naming, and static-analysis rules. The configuration files at the repository root are authoritative:

• .clang-format defines mechanical formatting.
• .clang-tidy defines naming and static-analysis checks.

VSAG requires clang-format 15 and clang-tidy 15 exactly. Other versions may produce different formatting or diagnostics and are not accepted by CI.

Code layout

• Put public APIs in include/vsag/ and implementation code in src/.
• Use .cpp for C++ source files, not .cc.
• Keep code in the vsag namespace unless the file clearly requires otherwise.
• Preserve API compatibility unless a breaking change is explicitly planned.
• Add or update Doxygen comments when changing a public API.
• Prefer uint64_t over size_t in new code to avoid macOS compatibility problems.
• Do not modify extern/ unless the change explicitly concerns a third-party dependency.
• End every committed text file with a trailing newline.

Formatting rules

The formatter starts from the Google style and applies the following VSAG rules:

For example, clang-format 15 formats a class declaration like this:

class Example {
public:
    Result<DatasetPtr>
    Build(const DatasetPtr& base, const std::string& parameters);

private:
    void
    reset_state();

    DatasetPtr dataset_;
};

The 100-column limit applies to C++ source and header files. It does not impose a line-width limit on Markdown or other non-C++ text.

Naming rules

The readability-identifier-naming check enforces these names:

make lint also runs scripts/linters/check-struct-names.py. It checks named struct definitions across tracked project C/C++ files, including files outside the normal clang-tidy source scope. Therefore, all new named structs must use CamelCase.

For entities without an explicit project rule, follow the Google C++ style and the convention in the surrounding code.

Choosing between class and struct

Use a struct for a passive, value-like data carrier:

• Its primary purpose is to group related values.
• Its data members are intentionally public and callers may modify them independently.
• It does not need to protect an invariant or hide a representation.
• It does not own a resource that requires controlled access or lifetime management.

Examples include Binary, SparseVector, and MultiVector. A struct may still have default member initializers, constructors, or small helper functions. Having a method does not by itself require using a class; the deciding factor is whether the type remains a transparent data value.

Use a class when the type represents behavior or must control its state:

• It maintains invariants through its public methods.
• It hides implementation details behind private or protected members.
• It owns or manages resources whose lifetime must be controlled.
• It provides a behavioral or polymorphic interface, especially one with virtual methods.

Examples include BinarySet, Dataset, Filter, and Index. Prefer class for new interfaces and polymorphic base types.

When unsure, ask whether callers should be allowed to change every data member directly and in any order. If yes, use struct; if the type must validate, coordinate, or restrict those changes, use class. Do not use struct merely to avoid writing public:, and do not expose mutable implementation details just to make a type aggregate-initializable.

Both classes and structs use CamelCase. Preserve the existing choice for a public type unless an intentional API change requires otherwise; do not switch between class and struct as a cosmetic cleanup.

Static analysis

All enabled clang-tidy diagnostics are treated as errors. The configuration enables the following check families:

• bugprone-* for likely logic defects and suspicious constructs.
• clang-analyzer-* for path-sensitive correctness and lifetime analysis.
• clang-diagnostic-* for compiler diagnostics exposed through clang-tidy.
• modernize-* for supported modern C++ practices.
• openmp-* for OpenMP correctness.
• performance-* for avoidable copies and inefficient operations.
• readability-* for maintainability and naming consistency.

Some checks are deliberately disabled because they conflict with VSAG’s low-level and performance-sensitive code or are too noisy for the current codebase:

A disabled check is not a recommendation to ignore the underlying concern. Use meaningful parameter names and named constants whenever they make the code clearer.

Suppressing a diagnostic

Fix the underlying issue whenever practical. If a diagnostic is a false positive or the construct is required for compatibility or performance, use the narrowest suppression and explain why it is safe:

// NOLINTNEXTLINE(performance-no-int-to-ptr): the platform API stores this handle as an integer.
auto* handle = reinterpret_cast<Handle*>(raw_handle);

Name the exact check in NOLINT, NOLINTNEXTLINE, or a tightly scoped NOLINTBEGIN/NOLINTEND pair. Avoid an unqualified NOLINT or a file-wide suppression unless there is no narrower practical option.

Running the checks

Install the required tools:

# Ubuntu or Debian
sudo apt-get install clang-format-15 clang-tidy-15 clang-tools-15

# macOS
brew install llvm@15

Format all project C++ files and inspect the resulting diff:

make fmt
git diff --check

clang-tidy requires a compilation database in build-release/, so create a release build first:

make release
make lint

The default lint target uses production .cpp files under src/ as clang-tidy entry points and excludes *_test.cpp. It also runs the repository-wide struct-name checker. Tests and other directories are not separate clang-tidy entry points in this command.

make fix-lint applies suggested replacements in place. It may make broad edits, so use it on a clean or safely backed-up working tree, review the complete diff, and rerun the checks and relevant tests:

make fix-lint
make fmt
make lint
make test

Before submitting a change

• Format all changed C++ files with clang-format 15.
• Run clang-tidy 15 for changed production sources.
• Ensure names follow the rules above, including CamelCase struct names.
• Keep every NOLINT check-specific and document its rationale.
• Add tests for new features and regression tests for bug fixes.
• Keep unit-test coverage for the C++ library at or above 90%.
• Run git diff --check and review the complete diff.

New Index Integration Checklist

Use this checklist when adding a new index implementation to VSAG. Keep the first pass small: make the index creatable through the public factory, support the lifecycle methods it advertises, and add feature flags only after the behavior is implemented and tested.

Required

• Choose the public index name and type.

  • Add the user-facing index name constant in include/vsag/constants.h or src/inner_string_params.h if the new index needs one.
  • Add an IndexType value in include/vsag/index.h when callers must distinguish this index through Index::GetIndexType().
  • Keep the public name stable. src/factory/index_registry.cpp normalizes factory names to lower case before lookup.

• Implement the index behind the public Index API.

  • Prefer the current IndexImpl<T> pattern in src/index/index_impl.h for new in-memory indexes: implement T as an InnerIndexInterface subclass under src/algorithm/<name>/.
  • Implement static CheckAndMappingExternalParam(const JsonType&, const IndexCommonParam&) so IndexImpl<T> can validate external JSON and construct the internal parameter object.
  • Implement GetName(), GetIndexType(), GetNumElements(), Add(), KnnSearch(), Serialize(StreamWriter&), and Deserialize(StreamReader&) as required by the inner-index contract; implement Build() when the index supports it. InnerIndexInterface::Add() is pure virtual, so every subclass must override it even when the index only supports Build() and should throw UNSUPPORTED_INDEX_OPERATION without enabling the corresponding feature flag.
  • Leave unsupported operations on the base class defaults instead of advertising them.

• Wire creation through the factory and engine path.

  • Add a creator in src/factory/index_creators.cpp.
  • Register it in register_all_index_creators().
  • Use IndexCommonParam::CheckAndCreate() from src/index_common_param.cpp for shared fields: dtype, metric_type, dim, optional repr, optional extra_info_size, allocator, thread pool, and old serialization format compatibility.
  • Add factory tests for the accepted name, invalid parameters, and unsupported parameter shapes in src/factory/factory_test.cpp or a focused test near the implementation.

• Add build-system wiring.

  • Add src/algorithm/<name>/CMakeLists.txt and include it from src/algorithm/CMakeLists.txt.
  • Add new sources to the closest existing target rather than creating a parallel build path.
  • Keep file suffixes as .cpp; do not edit extern/ unless the dependency itself is part of the change.

• Define and validate index parameters.

  • Put implementation parameters in a <name>_parameter.{h,cpp} pair when the index has its own schema.
  • Implement JSON parsing, ToJson(), and CheckCompatibility() for serialized/recreated parameter checks.
  • Reject invalid dimensions, metric/data-type combinations, missing required blocks, and unknown modes with ErrorType::INVALID_ARGUMENT through the existing CHECK_ARGUMENT / VsagException flow.
  • Update docs/docs/{en,zh}/src/resources/index_parameters.md and the per-index docs if the parameter becomes user-facing.

• Implement lifecycle behavior deliberately.

  • Decide whether the index supports Train(), Build(), ContinueBuild(), Add() after build, and Add() from empty.
  • Decide whether Remove(), UpdateId(), UpdateVector(), UpdateAttribute(), and UpdateExtraInfo() are supported.
  • For every supported mutation, test empty datasets, duplicate IDs if applicable, missing IDs, immutable index behavior, and search correctness after mutation.
  • Keep InitFeatures() in sync with the implemented operations.

• Implement search behavior and result packing.

  • Support the public KnnSearch() overloads required by the index, including BitsetPtr, std::function<bool(int64_t)>, and FilterPtr filtering when advertised.
  • Implement SearchWithRequest() if the index supports the newer request path.
  • Return Dataset fields consistently: IDs, distances, num_elements, result dimension, and optional result statistics.
  • Parse search parameters with the same nested index-name convention used by existing indexes such as HGraph.

• Preserve serialization compatibility.

  • Implement both Serialize(StreamWriter&) and Deserialize(StreamReader&); the base InnerIndexInterface adapts these to BinarySet, ReaderSet, and streams.
  • Store enough metadata to reject incompatible binaries, including parameter compatibility and extra_info_size when extra info is present.
  • Add round-trip tests through BinarySet and ReaderSet when the index supports both.
  • If the binary format changes for an existing index, update compatibility tests and document the migration path.

• Add tests before advertising features.

  • Unit tests should cover parameter parsing, build/add/search, serialization, feature flags, memory estimation if implemented, and error paths.
  • Functional tests under tests/ should cover public API behavior that users can reach through Factory::CreateIndex().
  • Keep C++ unit-test coverage for src/ and include/ at or above the project threshold.

Optional Adaptation Points

Add these only when the new index actually implements the behavior. When implemented, enable the matching IndexFeature values in InitFeatures() and add focused tests.

• Extra info (extra_info / extrainfo).

  • Parse extra_info_size through IndexCommonParam.
  • Store fixed-size per-vector payloads from Dataset::GetExtraInfos() and validate Dataset::GetExtraInfoSize() during Build(), Add(), and UpdateExtraInfo().
  • Implement GetExtraInfoByIds() and populate search-result extra info when the feature is supported.
  • If the index supports extra-info filtering, document and test the search parameter that switches Filter::CheckValid(const char*) on.
  • See docs/docs/en/src/advanced/extra_info.md and examples/cpp/320_feature_extra_info.cpp.

• Statistics and analysis.

  • Implement GetStats() for static structure data that helps operators understand an index.
  • Implement AnalyzeIndexBySearch(const SearchRequest&) only for query-driven analysis.
  • Include result statistics with Dataset::Statistics() when search-time metrics are useful.
  • Keep tool output compatible with tools/analyze_index and docs/docs/en/src/resources/analyze_index.md.

• Range search.

  • Override the pure-virtual primary RangeSearch(..., const FilterPtr&, ...) required by InnerIndexInterface, even when the algorithm does not support range search; in that case, throw UNSUPPORTED_INDEX_OPERATION without enabling the corresponding feature flag.
  • Implement the other RangeSearch() overloads only when the algorithm can honor radius semantics and limited_size.
  • Test no-limit, limited, filtered, and empty-result cases.
  • See docs/docs/en/src/advanced/range_search.md.

• Filters and attributes.

  • Support BitsetPtr, std::function<bool(int64_t)>, or FilterPtr only when each path is wired through search.
  • If attribute filtering is supported, implement attribute storage/update paths and document accepted attribute schemas.
  • Test the difference between bitset invalidation and Filter::CheckValid() keep semantics.

• Allocator, resource, and threading integration.

  • Allocate long-lived structures with IndexCommonParam::allocator_ or a derived allocator-aware component.
  • Use the Resource thread pool when build/search work is parallelized.
  • Verify custom allocator and custom thread-pool examples still describe the behavior accurately.
  • Mark concurrency features only after add/search/delete/update interactions are tested.

• Memory and introspection APIs.

  • Implement EstimateMemory(), EstimateBuildMemory(), GetMemoryUsage(), and GetMemoryUsageDetail() when the index can report meaningful numbers.
  • Implement GetMinAndMaxId(), CheckIdExist(), ExportIDs(), GetVectorByIds(), GetDataByIds(), GetIndexDetailInfos(), or GetDetailDataByName() only when the backing storage supports them.

• Model export, clone, merge, tune, and cache import/export.

  • Implement Clone() and ExportModel() when the index can be copied without sharing mutable storage incorrectly.
  • Implement Merge() only when parameter compatibility, ID remapping, and deletion semantics are clear.
  • Implement Tune(), ExportCache(), and ImportCache() only with explicit parameter parsing and tests.

• Bindings, examples, benchmarks, and docs.

  • Python bindings usually need updates only when the public API surface changes; current pyvsag users create indexes through names and JSON parameters.
  • Add C++ examples under examples/cpp/ when the index introduces a new user workflow.
  • Add Python examples/tests under tests/python/ if the behavior is reachable from pyvsag.
  • Add benchmark YAML under benchs/ when reviewers need repeatable performance data.
  • Add English and Chinese website docs under docs/docs/{en,zh}/src/ for user-facing indexes or parameters.

Review Checklist

• Factory::CreateIndex() and Engine::CreateIndex() create the index by the documented name.
• CheckFeature() returns true only for implemented and tested behavior.
• Unsupported operations return UNSUPPORTED_INDEX_OPERATION through existing wrappers.
• Serialization round trips preserve IDs, vectors or compressed codes, parameters, deletions, attributes, and extra info that the index claims to support.
• Search results remain valid after every supported lifecycle transition.
• Documentation lists user-facing parameters, supported metrics/data types, and unsupported operations.
• Practical validation has run: unit/functional tests for changed code, plus formatting or git diff --check for documentation-only changes.

Building

This page documents how to build VSAG from source.

Build phase and cache reporting

The collector preserves Ninja history for clean, warm-cache, and unchanged no-op phases. A no-op is verified only when available Ninja telemetry records zero build edges and the command succeeds; missing telemetry is explicitly unverified. Every observed category, including nested production modules such as datacell, tools, examples, and unclassified work, appears in JSON and Markdown. Multi-output edges count once. Cumulative edge time sums overlapping parallel durations and is not wall time; nested ExternalProject work is included in its parent edge rather than individually timed.

Cacheable-request hit rate is hits / (hits + misses). Available uncacheable reasons, including could_not_use_precompiled_header, are reported separately; missing counters and zero denominators are null in JSON and n/a in Markdown. Overall cache coverage is unavailable because compiler invocations bypassing ccache are not measured. Raw counters remain in JSON. This reporting does not change PCH or cache correctness settings.

Dependency preparation timers cover source preparation and archive restoration before configure, not all dependency work: further downloads, configuration, compilation and installation occur in configure/build phases. Peak RSS from /usr/bin/time -v is the maximum resident set size reported for the timed command and waited-for children, not the sum of simultaneously resident build processes.

Prerequisites

• OS: Ubuntu 20.04+, CentOS 7+, or macOS 14+ on Apple Silicon
• Compiler: GCC 9.4.0+, Clang 13.0.0+, or Apple Clang from Xcode Command Line Tools
• CMake: 3.18.0+
• Ninja: preferred when available; Unix Makefiles are used as the fallback
• clang-format / clang-tidy: exactly version 15 (enforced)
• Optional: HDF5 (for tools/eval/eval_performance), libaio (for the async_io data-cell backend), liburing (for uring_io on Linux), Intel MKL.

We recommend using the official Docker dev image, which already contains the matching toolchain:

docker pull vsaglib/vsag:ubuntu

Makefile Targets

Running make help prints a concise list; the most common targets are:

debug       Build debug binaries (no sanitizers; tests/tools/examples OFF by default)
release     Build release binaries (tests/tools/examples OFF by default)
dev         Developer build: debug + tests + tools + examples
test        Build with tests enabled and run unit + functional tests
cov         Build with coverage instrumentation enabled
asan        Build with AddressSanitizer
tsan        Build with ThreadSanitizer
fmt         Run clang-format
lint        Run clang-tidy
fix-lint    Apply clang-tidy fix-its in-place (destructive)
pyvsag      Build pyvsag for a specific Python version (PY_VERSION=...)
pyvsag-all  Build pyvsag wheels for all supported Python versions
dist-pre-cxx11-abi  Build redistributable tarball (pre-C++11 ABI)
dist-cxx11-abi      Build redistributable tarball (C++11 ABI)
dist-libcxx         Build redistributable tarball (libc++)
clean       Remove build trees

These targets prefer Ninja when a usable ninja executable is available. Otherwise they fall back to Unix Makefiles. An explicit generator always wins; for example, use make debug CMAKE_GENERATOR='Unix Makefiles' to request the fallback directly. Because CMake build trees are generator-specific, run the matching clean target before changing the generator for an existing build directory.

For configure/build targets, pass DEBUG_BUILD_DIR as a plain path, for example make asan DEBUG_BUILD_DIR="custom build". The shell removes these command-line quotes; the recipes quote the path when invoking CMake. Do not embed literal quote characters in the variable.

Dependency size metrics

The build metrics JSON uses schema version 3. Each dependency’s local_bytes (the Markdown report’s Local size) is an aggregate of file sizes, not allocated disk space. It replaces source_bytes and build_bytes: HDF5 and OpenBLAS build in their source trees, and ANTLR4’s binary directory is nested under its source tree, so those categories cannot be separated reliably.

For ExternalProject dependencies, the aggregate counts the entire dependency prefix once, including source, build, install, and any metadata inside that prefix. Shared BUILD_INFO_DIR files (by default .vsag-build-info: temporary files, stamps, logs, and metadata) are excluded from both local_bytes and the preparation table’s external_build_bytes; neither measures all ExternalProject storage. For FetchContent dependencies, it sums the sibling <name>-src and <name>-build trees. Symlink entries are excluded. Separately cached ExternalProject archives are reported in the preparation table, not added to local_bytes. System dependencies show zero because host installations are not measured; unclassified or missing trees also contribute zero. This is a snapshot of the measured local trees, not a source-only size or a measurement of generated build artifacts alone.

PR ASan builds and standalone build benchmarks

Legacy no-op measurements are not trustworthy until #2899. The standalone workflow deliberately fails its preflight on collectors without the supported schema 3 true_noop reporting. Separating PR builds does not itself fix the collector. While the prerequisite is unmerged, scheduled runs fail clearly instead of publishing misleading legacy baselines.

PR CI’s ASan Build X86 runs one make asan COMPILE_JOBS=3, with Ninja, compile commands, system OpenBLAS, examples and tools enabled. The Makefile still enables tests, Sanitize and ASan/UBSan; changed-source lint, downstream tests, compatibility checks and build artifacts retain their existing contracts. ccache --zero-stats resets counters, not cached objects. The build step logs elapsed time, and an always-run step prints verbose/fallback cache diagnostics without hiding a build failure. ccache stays enabled in its default directory on the disposable GitHub-hosted VM; no compiler cache is restored or saved between jobs. PR X86 dependency archives intentionally change from restore-and-save to restore-only (actions/cache/restore@v4), preventing PR contexts from writing archives back to the shared cache; this policy is not limited to the standalone benchmark.

The separate Build Performance Benchmark workflow (.github/workflows/build_performance.yml) runs weekly on Mondays at 03:23 UTC on upstream main, or manually from Actions. It is not a PR required check and uses separate concurrency, an Ubuntu 22.04 hosted runner, a 180-minute timeout and 14-day report retention. Once the workflow is on the default branch, for example:

gh workflow run build_performance.yml --ref main -f ref=main
# Or use a full 40-character commit SHA reachable from this repository's main:
gh workflow run build_performance.yml --ref main -f ref=<full-main-history-sha>

The workflow must itself be dispatched from main (other workflow branches are skipped). It explicitly checks out antgroup/vsag upstream main, accepts only main or a full SHA in that fetched upstream history, and records the actual checked-out SHA (not the dispatch event SHA) and the main baseline in target.txt. PR refs, arbitrary branches and unmerged feature commits are intentionally rejected. Therefore a draft migration branch cannot benchmark itself through this entry point; hosted dispatch and end-to-end validation remain pending until the workflow and supported collector are available on main. Scheduled execution is disabled on forks.

Security is deliberately conservative: read-only contents permission, no business secrets, no persisted checkout credentials, quoted environment input with SHA/ancestry validation, and a fixed workflow-owned Ubuntu package list instead of privileged installation scripts from the selected ref. Packages match the PR’s OpenBLAS-only host setup; keep these lists synchronized. Dependencies are checked out at pinned revisions by the existing composite action; download archives are restored without saving. There is no compiler-cache restore/save. The fresh benchmark job owns build/ and .benchmark-ccache; --clear-ccache never touches the normal PR cache. Default build/ retains compatibility with the existing collector/Makefile API.

“Cold” means a clean build with an empty compiler cache, not a cold network or dependency-source download. The collector’s existing CLI measures configure → cold build → clean → warm ccache rebuild → no-op without another clean between warm and no-op. Reports include JSON, Markdown, phase logs, peak RSS, Ninja statistics and ccache details; toolchain.txt records tool versions and actual workflow environment values, while collector-command.txt records the shell-escaped collector invocation executed by the workflow. The collector’s phase logs remain authoritative for the underlying build commands/options; dependency preparation time/cache metadata remain in its report. The compiler-cache key is descriptive metadata, not evidence of restored cache. Parallel cumulative edge time is not wall time, and cache hit rates do not cover bypassed/PCH/link work; missing telemetry must not be read as zero.

The preflight checks the known schema 3 capability without executing the collector; it is not a proof of measurement correctness. After collection, the workflow additionally requires success, available Ninja telemetry, true_noop: true and zero build edges. #2899 can report a false no-op without failing collection, so this workflow fails such runs and preserves their raw reports for diagnosis. Residual generated/check edges require inspecting the logs and the collector’s build-edge classification. Unknown future schemas fail closed until reviewed. This trades temporary red/absent baselines for avoiding confidently mislabeled measurements; do not bypass the gate to restore legacy reports. Recheck #2899’s final API and tests after merge, including missing logs, rewritten history, multi-output edges and source/header rebuilds. This migration does not modify the collector, PCH, compiler flags or persistent caching.

Step-by-Step

git clone https://github.com/antgroup/vsag.git
cd vsag
./scripts/deps/install_deps.sh
make release

The dependency script selects the matching Linux distribution or macOS installer. macOS support currently targets the arm64 C++ build; published archives and Python wheels remain Linux-focused.

Resulting binaries from a plain make release:

• Library: build-release/src/libvsag.{a,so}

Examples and tools are not built by default. To include them, either use make dev, or enable the corresponding Makefile variables (VSAG_ENABLE_EXAMPLES=ON, VSAG_ENABLE_TOOLS=ON) or the underlying CMake cache options (-DENABLE_EXAMPLES=ON, -DENABLE_TOOLS=ON).

Environment Variables / CMake Options

The Makefile exposes a few VSAG_ENABLE_* environment variables that are translated into CMake cache options (ENABLE_*). Defaults below reflect a plain make release.

When invoking CMake directly instead of using make, use the underlying CMake cache option names:

cmake -S . -B build-release -DCMAKE_BUILD_TYPE=Release -DENABLE_INTEL_MKL=ON
cmake --build build-release -j

To enable io_uring, install liburing and add -DENABLE_LIBURING=ON. On non-Linux systems or when liburing is unavailable, VSAG compiles without native io_uring support; a configuration that requests uring_io then logs a one-time warning and falls back to buffer_io.

Offline / Air-gapped Builds

VSAG downloads its third-party libraries at configure/build time. In offline or restricted-network environments, set the per-dependency VSAG_THIRDPARTY_* environment variables to fetch each archive from a local path or an internal mirror (internal HTTP server, object storage, etc.). See Offline / Air-gapped Builds for the full list of variables and worked examples.

Python Wheel (pyvsag)

make pyvsag PY_VERSION=3.10
# Or build all supported versions in parallel:
make pyvsag-all

Wheels are emitted under python/dist/.

Distribution Tarballs

For ABI-compatible redistribution use one of:

make dist-pre-cxx11-abi   # _GLIBCXX_USE_CXX11_ABI=0
make dist-cxx11-abi       # _GLIBCXX_USE_CXX11_ABI=1
make dist-libcxx          # libc++ (Clang)

The produced tarballs contain headers, static/shared libraries, and version metadata.

Release Publishing

To publish a new GitHub Release, use the Build and Publish Release workflow in the GitHub Actions tab and run it manually with:

• branch: the branch, tag, or commit SHA to release from
• tag_name: the new release tag, such as v1.0.0
• prerelease: whether to mark the release as a prerelease

For a local dry run of the same packaging script, run:

COMPILE_JOBS=6 bash ./scripts/release/dist.sh

For accelerated dependency downloads in both ABI containers, optionally set VSAG_THIRDPARTY_ENV_FILE to a readable regular file on the host (quote paths containing spaces):

VSAG_THIRDPARTY_ENV_FILE="/path/to/dependency urls.env" bash ./scripts/release/dist.sh

Use ASCII VSAG_THIRDPARTY_<NAME>=URL lines, with uppercase letters, digits and underscores in names, including pin-qualified names. URLs must start with a scheme such as https:// and contain no whitespace; do not use export, quotes or inline comments. Blank lines and full-line # comments are allowed; LF, CRLF and a missing final newline work. Values are literal: =, &, # and $ are preserved without shell expansion. Duplicate keys, invalid entries and lines longer than 65,534 bytes (excluding line endings) fail before image builds. File values override image defaults; host dependency variables are not forwarded or modified. CMake prefers pinned names over legacy names and retains default URLs as download fallbacks. An unset path preserves existing behavior; an explicitly empty or unreadable path is an error.

You can increase COMPILE_JOBS if your machine has enough memory, but the default is conservative to avoid out-of-memory failures in CI runners.

Offline / Air-gapped Builds

VSAG downloads a set of third-party libraries at CMake configure / build time (via ExternalProject_Add and FetchContent). On a machine without internet access, or behind a slow / restricted network, those downloads can fail or time out. This page explains how to point each dependency at a local path or an internal mirror (internal HTTP server, object storage, Artifactory, etc.) so the build can complete fully offline.

How third-party downloads are resolved

For every downloaded dependency, VSAG builds a list of candidate URLs and lets CMake try them in order, stopping at the first one that succeeds. Using antlr4 as the representative example (extern/antlr4/antlr4.cmake):

set (antlr4_urls
    https://github.com/antlr/antlr4/archive/refs/tags/4.13.2.tar.gz
)
vsag_resolve_thirdparty_override (ANTLR4 4.13.2 antlr4_urls)

ExternalProject_Add (antlr4
    URL ${antlr4_urls}
    URL_HASH MD5=3b75610fc8a827119258cba09a068be5
    ...)

The resolution order is therefore:

1. The pinned variable, VSAG_THIRDPARTY_<LIB>_<PIN_SUFFIX>, for the exact dependency identifier used by the current branch.
2. The unversioned VSAG_THIRDPARTY_<LIB> variable, as a deprecated compatibility fallback. If both variables are set, the pinned variable wins.
3. The authoritative upstream URL or URLs (GitHub / project release page).

VSAG does not provide a project-controlled archive mirror. For a local or internal mirror, set the pinned variable (preferred) or the deprecated legacy variable.

Only the pinned variable for the branch’s exact pin is read. Pinned variables for other versions can remain exported and are ignored. This lets one CI image or shell profile safely support several VSAG branches at once.

Pinned-variable names

The suffix is derived from the exact pinned identifier:

• Numeric releases strip one leading v/V and a dependency-name decoration immediately before the number. ASCII letters are uppercased and runs of other characters become one underscore. Thus 10.2.1 and v10.2.1 become 10_2_1, hdf5_1.14.4 becomes 1_14_4, and yaml-cpp-0.9.0 becomes 0_9_0.
• A full commit hash becomes COMMIT_<12_HEX>, for example VSAG_THIRDPARTY_CPUINFO_COMMIT_CA678952A9A8.
• Other tags and refs become TAG_<NORMALIZED>_H<12_HEX>. The hexadecimal part is the uppercase prefix of SHA-256 over the exact, case-sensitive identifier, so spellings that normalize alike remain distinguishable.
• If two pins for one dependency collide at 12 hexadecimal characters, both names extend deterministically one character at a time. Configuration fails instead of accepting an ambiguous name if the full hash or digest cannot distinguish them.

Key facts before you start

• The value may be a local path or a URL. Accepted forms include an absolute filesystem path (/data/deps/fmt-10.2.1.tar.gz), a file:// URL, or any http(s):// URL — including an internal HTTP server or object storage.
• The archive hash is still verified. Each dependency declares a URL_HASH (MD5 or SHA256). Your mirrored / local archive must be byte identical to the upstream archive, otherwise CMake aborts with a hash mismatch. The simplest safe approach is to download the exact upstream file once and re-host it unchanged.
• Overrides are read at configure time. If you change a variable after a previous configure, re-run CMake configure or run make clean first so the new value takes effect.
• Use a non-empty value, or leave it unset. CMake treats a variable that is exported but empty as defined, so export VSAG_THIRDPARTY_FMT_10_2_1= would prepend an empty entry to the URL list and break the download. To disable an override, unset it instead of setting it to an empty string.
• Each dependency is independent. There is no single global mirror variable; set one pinned variable per dependency you need. You only need to set variables for the dependencies your build actually pulls in (see Which dependencies do I need?).
• Confirmation in the log. CMake reports the dependency, pin, selected source category and variable, plus fallback/deprecation behavior. It intentionally does not print the value because URLs can contain credentials.

Environment variables

The exact upstream URL and the expected URL_HASH for each dependency are the single source of truth in the corresponding extern/<lib>/<lib>.cmake file. Check that file when mirroring, especially after a version bump.

Not listed here (no download, so no override needed): Intel MKL, which is located on the host with find_path.

Which dependencies do I need?