zvec

Executes approximate nearest neighbor search directly within application memory using Hierarchical Navigable Small World (HNSW) graph indexes, eliminating network latency and external server dependencies. Implements multi-layer graph traversal with configurable M (max connections) and ef (search expansion factor) parameters to balance recall vs latency tradeoffs. Supports both dense and sparse vector embeddings within a single collection, with native handling of variable-dimension vectors through the zvec_core search engine.

Combines dense vector similarity search with structured scalar filters (e.g., date ranges, categorical tags) through a unified SQL query engine that optimizes filter pushdown and index selection. The query planner analyzes predicates to determine whether to apply filters before (pre-filter) or after (post-filter) vector search, minimizing irrelevant vector comparisons. Supports complex boolean expressions on metadata fields while maintaining vector search semantics through the zvec_db layer's query interface.

Accepts multiple vectors and metadata in a single batch operation, buffering them in memory until a configurable threshold (e.g., 100k vectors) is reached, then automatically flushing to a new segment. Batch insertion amortizes the cost of segment creation and metadata updates across multiple vectors, improving throughput compared to single-vector inserts. The flush operation is asynchronous; queries can proceed while new segments are being written to disk.

Provides an abstraction layer for embedding functions that can be registered with a collection, enabling automatic embedding computation during insertion and query. Supports pluggable re-rankers that post-process search results using alternative similarity metrics (e.g., cross-encoder models) to improve ranking quality. Re-rankers are applied transparently after vector search, trading ~10-50% latency overhead for improved result quality.

Executes queries in parallel across multiple segments, with each segment searched independently and results merged at the end. The query executor uses thread pools to parallelize segment searches, enabling multi-core utilization for large collections with many segments. Concurrent queries on different collections do not block each other; read-write conflicts are avoided through segment immutability.

Stores index segments as binary files on disk with memory-mapped access, enabling efficient loading of large indexes without copying data into memory. Segment files include metadata headers (vector count, dimension, index type, quantization parameters) followed by index data. Memory-mapped access allows the OS to page segments in/out based on access patterns, enabling indexes larger than physical RAM. Checksums protect against corruption.

Compresses vector embeddings using Rotation-Aware Bit Quantization (RaBitQ) to reduce memory footprint and accelerate distance computations, then re-ranks top-k candidates using original full-precision vectors to recover recall lost during quantization. The quantization pipeline learns rotation matrices per segment to align high-variance dimensions, enabling 8-16x compression while maintaining >95% recall. Re-ranking is applied transparently during query execution, trading ~5-10% latency overhead for dramatic memory savings.

Provides three index types optimized for different recall-latency-memory tradeoffs: HNSW for balanced performance on medium-scale datasets (millions of vectors), IVF (Inverted File) for very large-scale datasets (billions of vectors) with coarse quantization, and Flat (brute-force) for small datasets or when 100% recall is required. The schema definition allows specifying index type and parameters (e.g., HNSW M=16, IVF nlist=1000) per collection, with automatic index selection based on dataset size heuristics if not explicitly configured.

Organizes data into immutable segments that are independently indexed and queried, enabling efficient incremental updates without full index rebuilds. New vectors are written to a mutable buffer that periodically flushes to a new segment; queries transparently search all segments and merge results. Segments are stored as binary files with metadata headers, supporting both in-memory and memory-mapped access patterns. This architecture enables concurrent reads while writes are buffered, avoiding lock contention.

Automatically detects CPU capabilities at runtime and dispatches distance computations to optimized SIMD kernels (AVX-512 VNNI, AVX2, SSE) without manual configuration. The ailego utility library provides vectorized implementations of L2, cosine, and inner product distances, with specialized kernels for quantized vectors. CPU Auto-Dispatch eliminates the need for separate binaries per architecture, enabling single-binary deployments across heterogeneous hardware (x86_64, ARM64).

Exposes zvec's C++ core through a Pythonic API using pybind11, providing classes like CollectionSchema, VectorQuery, and Doc for intuitive data manipulation. The bindings maintain zero-copy semantics for vector data, avoiding serialization overhead when passing large arrays between Python and C++. Type hints and docstrings enable IDE autocompletion and documentation discovery, while exception handling translates C++ errors to Python exceptions.

Provides a standalone CLI tool (local_builder) that pre-computes HNSW and IVF indexes from raw vector files without loading data into memory, enabling efficient batch index construction for billion-scale datasets. The tool reads vectors from binary or text formats, applies quantization if specified, and writes index segments to disk. This decouples index construction (expensive, one-time) from query serving (latency-critical), enabling offline preprocessing on high-memory machines before deploying to resource-constrained environments.

Defines collection structure through CollectionSchema and VectorSchema classes that specify vector dimensions, data types, index parameters, and metadata fields with explicit types (string, int, float, bool). Schema validation occurs at collection creation time, preventing runtime type mismatches. Metadata fields can be indexed for efficient filtering, and schema can be introspected at runtime to enable dynamic query construction.

Exposes zvec functionality through a C API (C99 compatible) that enables integration with any language supporting C FFI (Go, Rust, Java, C#, etc.). The C API provides opaque pointers to collections, queries, and results, with explicit memory management functions (malloc/free) for language binding authors. C API examples demonstrate integration patterns for common languages, enabling teams to build language-specific wrappers without modifying zvec core.