Factory & Engine

Every VSAG workflow begins by obtaining an Index. There are two entry points:

• Factory — the simplest way to create an index or a file reader. It uses a default (or caller-supplied) allocator and manages resources internally.
• Engine — an explicit owner of shared resources (allocator + thread pool). Use it when you want several indexes to share one memory allocator / thread pool, or when you need deterministic control over resource lifetime.

This page also documents the process-level initialization helpers and the top-level helper functions for parameter generation and validation.

Library initialization

#include <vsag/vsag.h>

vsag::init();                       // call once, before any other API
std::string ver = vsag::version();  // e.g. the git-derived build string

Factory

Declared in vsag/factory.h. Factory is a stateless utility class with only static methods; it cannot be instantiated.

CreateIndex

static tl::expected<std::shared_ptr<Index>, Error>
CreateIndex(const std::string& name,
            const std::string& parameters,
            Allocator* allocator = nullptr);

Creates an index of the given type.

Returns a std::shared_ptr<Index> on success, or an Error (typically UNSUPPORTED_INDEX for an unknown name, or INVALID_ARGUMENT for malformed parameters).

auto index = vsag::Factory::CreateIndex("hgraph", R"(
{
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 128,
    "index_param": { "base_quantization_type": "sq8" }
})");
if (not index.has_value()) {
    std::cerr << index.error().message << std::endl;
    return;
}
std::shared_ptr<vsag::Index> hgraph = index.value();

CreateLocalFileReader

static std::shared_ptr<Reader>
CreateLocalFileReader(const std::string& filename, int64_t base_offset, int64_t size);

Creates a Reader that reads a window of a local file starting at base_offset for size bytes. This is most often used to build a ReaderSet for streaming deserialization of on-disk indexes. Unlike the methods above, it returns a plain std::shared_ptr (there is no fallible Error channel).

Engine

Declared in vsag/engine.h. An Engine binds a Resource (allocator + thread pool) and lets you create indexes that share it. The engine never takes ownership of a Resource* passed to it; you control its lifetime.

vsag::Resource resource(vsag::Engine::CreateDefaultAllocator().get(), nullptr);
vsag::Engine engine(&resource);

auto index = engine.CreateIndex("hgraph", params);
// ... use index ...

engine.Shutdown();   // release engine-held state; warns on dangling references

Constructor & lifecycle

CreateIndex

[[nodiscard]] tl::expected<std::shared_ptr<Index>, Error>
CreateIndex(const std::string& name, const std::string& parameters);

Same semantics as Factory::CreateIndex, except the index is created against the engine’s shared Resource (allocator and thread pool) instead of a per-call allocator.

Static resource helpers

See Resource Management for how Resource, Allocator, and ThreadPool fit together, and examples/cpp/201_custom_allocator.cpp / 203_custom_thread_pool.cpp for runnable samples.

Top-level helper functions

These free functions (declared in vsag/index.h) help you generate and validate configuration strings before creating an index. All return tl::expected<..., Error>.

generate_build_parameters

tl::expected<std::string, Error>
generate_build_parameters(std::string metric_type,
                          int64_t num_elements,
                          int64_t dim,
                          bool use_conjugate_graph = false);

(Experimental.) Produces a suggested build-parameter JSON string from the dataset shape (metric_type, num_elements, dim). Pass use_conjugate_graph = true to enable conjugate-graph enhancement.

estimate_search_time

tl::expected<float, Error>
estimate_search_time(const std::string& index_name,
                     int64_t data_num,
                     int64_t data_dim,
                     const std::string& parameters);

Estimates the per-query search time (in milliseconds) for the given index type and configuration.

check_diskann_hnsw_build_parameters / check_diskann_hnsw_search_parameters

tl::expected<bool, Error>
check_diskann_hnsw_build_parameters(const std::string& json_string);

tl::expected<bool, Error>
check_diskann_hnsw_search_parameters(const std::string& json_string);

Validate DiskANN/HNSW build and search parameter JSON respectively. On success the value is true; on failure the Error message explains what is wrong. See the Compatibility Check Tool for a CLI wrapper around this kind of validation.

See also

• Index — what you can do with the index once it is created.
• Resource Management — allocator, thread pool, and Resource details.
• Index Parameters — the JSON schema accepted by CreateIndex.