Overview

Relevant source files

• .github/ISSUE_TEMPLATE/config.yml
• .github/workflows/05-windows-build.yml
• .pre-commit-config.yaml
• CMakeLists.txt
• CONTRIBUTING.md
• README.md
• cmake/option.cmake
• examples/c++/core/main.cc
• examples/c++/db/main.cc
• tests/CMakeLists.txt
• thirdparty/CRoaring/CMakeLists.txt
• tools/core/README.md

zvec is an open-source, in-process vector database designed to be lightweight, lightning-fast, and directly embedded into applications README.md30-31 Built on Proxima (Alibaba's battle-tested vector search engine), it provides production-grade similarity search with minimal configuration README.md30-31

As an in-process library, zvec eliminates the need for external server management, running wherever your application code runs—from local notebooks and CLI tools to high-performance servers README.md47-48

Key Capabilities

• High Performance: Capable of searching billions of vectors in milliseconds with optimized SIMD kernels README.md43
• Hybrid Search: Supports combining semantic vector similarity with structured scalar filters README.md46
• Multi-Vector Support: Native support for both dense and sparse embeddings within a single collection README.md45
• Storage Flexibility: Supports multiple index types including HNSW, IVF, and RaBitQ quantization examples/c++/core/main.cc52-57 README.md36
• Efficiency: Features RaBitQ quantization and CPU Auto-Dispatch for optimized SIMD execution across various architectures README.md36 cmake/option.cmake45-52
• Broad Platform Support: Runs on Linux (x86_64, ARM64), macOS (ARM64), and Windows (x86_64) README.md65-70

For a step-by-step guide on installation and your first query, see Getting Started.

System Architecture

The zvec architecture is composed of layers that bridge high-level application logic to hardware-accelerated search kernels.

High-Level Component Interaction

The following diagram illustrates how the major subsystems relate, from the Python/Node.js entry points down to the core engine and persistence layer.

System Component Map

Sources: README.md51-64 examples/c++/db/main.cc168-188 CMakeLists.txt58-62 README.md36-37

Major Subsystems

1. Python API & Bindings

The primary interface for users is the Python package, which provides intuitive classes like CollectionSchema, VectorQuery, and Doc to manage data README.md77-103 It uses pybind11 to wrap the C++ implementation CMakeLists.txt58-59

• Key Entities: zvec.CollectionSchema, zvec.VectorSchema, zvec.Doc, zvec.VectorQuery README.md81-99
• For details on the data model and query interface, see Key Concepts and Terminology.

2. Database Layer (zvec_db)

This layer manages the lifecycle of collections, schemas, and data persistence. It supports a wide variety of data types including scalars (INT32, STRING, etc.) and vectors (FP32, FP16, INT8, Sparse) examples/c++/db/main.cc21-162

• Key Entities: CollectionSchema examples/c++/db/main.cc168-169 FieldSchema examples/c++/db/main.cc172-173 Doc examples/c++/db/main.cc12-14

3. Core Search Engine (zvec_core)

The algorithmic heart of zvec, containing implementations for Approximate Nearest Neighbor (ANN) search. It utilizes an IndexFactory to instantiate various index types like HNSW or IVF based on configuration examples/c++/core/main.cc4-5 examples/c++/core/main.cc16

• Key Entities: IndexFactory, Index, HNSWIndexParamBuilder, HNSWQueryParamBuilder examples/c++/core/main.cc4-7

4. Utility Library (ailego)

A low-level library providing hardware abstraction. It includes SIMD-accelerated math kernels with auto-detection for CPU features like AVX-512 and AVX2 cmake/option.cmake127-189 CMakeLists.txt50-53

Code Entity Mapping

The following diagram bridges the conceptual subsystems to specific code entities and library targets within the repository.

Code Entity Space Bridge

Sources: examples/c++/db/main.cc5-8 examples/c++/core/main.cc4-7 CMakeLists.txt75-80 README.md36-37

Development and Tooling

Zvec includes a robust set of tools for performance evaluation and offline index construction:

• local_builder: For building large-scale indices from raw vector files tools/core/README.md136
• recall: For measuring the accuracy of ANN indices against ground truth tools/core/README.md142
• bench: For high-concurrency performance benchmarking tools/core/README.md147
• Build Customization: Controlled via CMake options like ENABLE_SKYLAKE_AVX512 and BUILD_PYTHON_BINDINGS CONTRIBUTING.md72-76 CMakeLists.txt58

Sources: README.md30-31 CONTRIBUTING.md12-46 CMakeLists.txt64-67 tools/core/README.md91-148