# alibaba/zvec architecture

> Architecture diagram of the GitHub repository alibaba/zvec, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alibaba/zvec
- Repository: https://github.com/alibaba/zvec

## Overview

1. **Repository purpose and top-level shape**
   - Zvec is an **in-process vector database**: it runs inside the host application rather than as a separate server.
   - The codebase is organized into a **public API layer**, a **database/query layer**, a **core indexing engine**, and a **low-level performance library** (`ailego` / `turbo`), with bindings and tools around the edges.

2. **Public entry points**
   - The primary user-facing surfaces are the **C API** (`src/include/zvec/c_api.h`, `src/binding/c`) and the **Python package** (`python/zvec`, `src/binding/python`).
   - The Python package wraps collections, schemas, docs, query parameters, and extension functions for embeddings/reranking. It mirrors the C++ object model rather than implementing its own storage engine.

3. **Database layer: collections, schema, query, rerank**
   - `src/db` is the main database orchestration layer. It defines collections, schema, docs, query objects, status/error handling, and runtime config.
   - This layer is what ties together user operations like create/open, insert, update, delete, and query with the underlying index/storage implementations.
   - `src/db/reranker` and Python extensions provide reranking hooks after candidate retrieval.

4. **SQL and hybrid query processing**
   - `src/db/sqlengine` parses and plans higher-level queries, including full-text search, vector recall, structured filters, ordering, and hybrid combinations.
   - The flow is: SQL/query text → parser/analyzer → planner/optimizer → execution plan nodes, which then call into segment and index primitives.
   - This is the main boundary where “query intent” is translated into concrete recalls over vectors, inverted indexes, and filters.

5. **Indexing architecture: pluggable index families**
   - `src/core/interface` and `src/core/framework` define the common index abstraction: builders, searchers, streamers, reducers, reformers, metrics, storage, and lifecycle hooks.
   - Concrete vector index families live under `src/core/algorithm`, including **flat**, **HNSW**, **HNSW sparse**, **HNSW RaBitQ**, **IVF**, **DiskANN**, and **Vamana**.
   - Each family follows a similar shape: build/train/index, search, and streaming/persistence support, which makes them interchangeable from the higher layers.

6. **Full-text and inverted indexing path**
   - Full-text search is implemented in the DB layer under `src/db/index/column/fts_column`.
   - It includes tokenization pipelines, ANTLR-generated query parsing, posting lists, BM25 scoring, and iterators for conjunction/disjunction/phrase/term matching.
   - Separate inverted-column code handles non-vector scalar/text-like filters and acts as part of the hybrid retrieval pipeline.

7. **Storage, persistence, and crash recovery**
   - Persistent data is handled through `src/db/index/storage`, including memory-backed, mmap-backed, bufferpool-backed, Arrow IPC, Parquet, and chunked file writers/readers.
   - WAL support is explicit in `src/db/index/storage/wal`, with local WAL file implementations for durability and recovery.
   - The README’s crash-safety guarantee comes from this layer: writes are logged, and collections can be reopened after failure.

8. **Segment model and incremental layout**
   - `src/db/index/segment` and related helpers represent the on-disk/in-memory organization of a collection as segments.
   - Segments provide the unit for merging, reading, query-time dispatch, and combining results across columns/indexes.
   - This is the main data partitioning boundary between collection-level operations and individual index structures.

9. **Core math, quantization, and CPU acceleration**
   - `src/ailego` and `src/turbo` provide the performance foundation: vector math, distance matrices, quantizers, SIMD/dispatch implementations, thread pools, file and memory utilities, and CPU feature detection.
   - The math subsystem includes multiple distance families: cosine, Euclidean, inner product, MIPS-to-Euclidean transforms, and quantized integer variants.
   - A lot of architecture-critical performance comes from runtime dispatch across x86/AVX/AVX512/NEON/SSE and specialized FP16/int8/int4 kernels.

10. **Conversion/reformation and mixed precision support**
   - `src/core/quantizer` and `src/core/metric` convert raw user vectors into index-specific internal formats.
   - Reformers/converters support binary, half-float, integer quantization, uniform int8, cosine, and MIPS transformations.
   - This is the boundary where ingestion data is normalized for the chosen index and metric, and where search-time scoring is aligned with storage format.

11. **Plugin and extension points**
   - `src/core/plugin` and `src/include/zvec/plugin` show that some index capabilities are delivered as plugins, not just built-ins.
   - The `DiskANN` plugin is the notable example, matching the repo’s emphasis on pluggable large-scale retrieval backends.
   - Extension points are also exposed in Python for external embedding functions and rerankers, which affect query-time behavior but live outside the core engine.

12. **Build, packaging, and portability**
   - The project is CMake-driven, with platform-specific build support for Linux, macOS, Windows, Android, iOS, and RISC-V visible in workflows and scripts.
   - Third-party dependencies are vendored under `thirdparty` and include RocksDB, Arrow, ANTLR, Protobuf, glog/gflags, cppjieba, CRoaring, FastPFOR, RaBitQ, and others.
   - This matters architecturally because the repo is designed to produce both native libraries and language bindings from the same core C++ implementation.

13. **Validation and operational tooling**
   - `tests` mirrors the architecture closely: low-level utility tests, core algorithm tests, DB/segment/storage tests, SQL engine tests, and crash-recovery tests.
   - `examples` demonstrates the public API shape for C and C++, while `tools` includes benchmarking, local build/recall utilities, and text-to-vector conversion helpers.
   - The CI workflows indicate the project is validated across multiple platforms and build targets, reinforcing that portability is part of the architecture.

14. **End-to-end data flow to diagram**
   - Typical flow: application calls Python/C/C++ API → collection/schema/query objects in `db` → SQL engine or direct index path → segment dispatch → concrete index/searcher/FTS/inverted store → candidate ranking/refinement → results returned to caller.
   - Inserts and updates additionally flow through WAL and storage backends before becoming searchable.
   - Hybrid queries can fan out across vector indexes, FTS, and filters, then merge/re-rank results in the DB/query layer.

Main entry points: [`src/db/sqlengine`](https://github.com/alibaba/zvec/tree/main/src/db/sqlengine) (SQL engine), [`src/db/collection.cc`](https://github.com/alibaba/zvec/blob/main/src/db/collection.cc) (Collection), [`src/db/index/segment`](https://github.com/alibaba/zvec/tree/main/src/db/index/segment) (Segments), [`src/core/algorithm`](https://github.com/alibaba/zvec/tree/main/src/core/algorithm) (Vector families)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public_api["Public API"]
  node_c_api["C API<br/>[c_api.h]"]
  node_python_pkg["Python API<br/>binding"]
end

subgraph group_db_layer["DB Layer"]
  node_collection["Collection<br/>db orchestrator<br/>[collection.cc]"]
  node_schema_doc["Schema & docs<br/>db model"]
  node_db_common["DB common<br/>support"]
  node_sqlengine["SQL engine<br/>query planner"]
  node_reranker["Reranker<br/>query refine<br/>[reranker.cc]"]
end

subgraph group_index_engine["Core Engine"]
  node_segment["Segments<br/>layout"]
  node_vector_cols["Vector columns<br/>column index"]
  node_fts_column["Full text<br/>text index"]
  node_inverted_column["Inverted column<br/>filter index"]
  node_storage_wal[("Storage & WAL<br/>persistence")]
  node_index_iface["Index framework<br/>abstraction"]
  node_framework["Framework<br/>orchestration"]
  node_algorithms["Vector families<br/>indexes"]
  node_quantizer_metric["Metric & quantize<br/>format adapter"]
end

subgraph group_perf_lib["Perf Library"]
  node_ailego["ailego<br/>math/runtime"]
  node_turbo["turbo<br/>kernel lib"]
end

subgraph group_integration["Integration"]
  node_python_binding["Py binding<br/>native bridge"]
  node_c_binding["C binding<br/>native bridge"]
  node_plugin["Plugins<br/>extension"]
  node_examples["Examples<br/>usage"]
  node_tools["Tools<br/>bench/util"]
end

node_python_pkg -->|"wraps"| node_python_binding
node_python_binding -->|"calls"| node_c_api
node_c_binding -->|"exports"| node_c_api
node_c_api -->|"opens"| node_collection
node_collection -->|"uses"| node_schema_doc
node_collection -->|"depends"| node_db_common
node_collection -->|"queries"| node_sqlengine
node_collection -->|"organizes"| node_segment
node_sqlengine -->|"plans to"| node_segment
node_sqlengine -->|"recalls"| node_vector_cols
node_sqlengine -->|"full-text"| node_fts_column
node_sqlengine -->|"filters"| node_inverted_column
node_sqlengine -->|"re-ranks"| node_reranker
node_segment -->|"persists"| node_storage_wal
node_segment -->|"hosts"| node_vector_cols
node_segment -->|"hosts"| node_fts_column
node_segment -->|"hosts"| node_inverted_column
node_vector_cols -->|"implements"| node_index_iface
node_fts_column -->|"stores"| node_storage_wal
node_inverted_column -->|"stores"| node_storage_wal
node_index_iface -->|"adapts"| node_framework
node_framework -->|"loads"| node_algorithms
node_framework -->|"extends"| node_plugin
node_algorithms -->|"normalizes"| node_quantizer_metric
node_quantizer_metric -->|"uses"| node_ailego
node_algorithms -->|"accelerates"| node_ailego
node_turbo -->|"accelerates"| node_ailego
node_plugin -->|"provides"| node_algorithms
node_python_pkg -->|"extends"| node_reranker
node_examples -->|"demonstrates"| node_c_api
node_examples -->|"demonstrates"| node_collection
node_tools -->|"benchmarks"| node_sqlengine
node_tools -->|"measures"| node_algorithms

click node_c_api "https://github.com/alibaba/zvec/blob/main/src/include/zvec/c_api.h"
click node_python_pkg "https://github.com/alibaba/zvec/tree/main/python/zvec"
click node_python_binding "https://github.com/alibaba/zvec/tree/main/src/binding/python"
click node_c_binding "https://github.com/alibaba/zvec/tree/main/src/binding/c"
click node_collection "https://github.com/alibaba/zvec/blob/main/src/db/collection.cc"
click node_schema_doc "https://github.com/alibaba/zvec/tree/main/src/include/zvec/db"
click node_db_common "https://github.com/alibaba/zvec/tree/main/src/db/common"
click node_sqlengine "https://github.com/alibaba/zvec/tree/main/src/db/sqlengine"
click node_reranker "https://github.com/alibaba/zvec/blob/main/src/db/reranker/reranker.cc"
click node_segment "https://github.com/alibaba/zvec/tree/main/src/db/index/segment"
click node_vector_cols "https://github.com/alibaba/zvec/tree/main/src/db/index/column/vector_column"
click node_fts_column "https://github.com/alibaba/zvec/tree/main/src/db/index/column/fts_column"
click node_inverted_column "https://github.com/alibaba/zvec/tree/main/src/db/index/column/inverted_column"
click node_storage_wal "https://github.com/alibaba/zvec/tree/main/src/db/index/storage"
click node_index_iface "https://github.com/alibaba/zvec/tree/main/src/core/interface"
click node_framework "https://github.com/alibaba/zvec/tree/main/src/core/framework"
click node_algorithms "https://github.com/alibaba/zvec/tree/main/src/core/algorithm"
click node_quantizer_metric "https://github.com/alibaba/zvec/tree/main/src/core/quantizer"
click node_plugin "https://github.com/alibaba/zvec/tree/main/src/core/plugin"
click node_ailego "https://github.com/alibaba/zvec/tree/main/src/ailego"
click node_turbo "https://github.com/alibaba/zvec/tree/main/src/turbo"
click node_examples "https://github.com/alibaba/zvec/tree/main/examples"
click node_tools "https://github.com/alibaba/zvec/tree/main/tools"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_c_api,node_python_pkg toneBlue
class node_collection,node_schema_doc,node_db_common,node_sqlengine,node_reranker toneAmber
class node_segment,node_vector_cols,node_fts_column,node_inverted_column,node_storage_wal,node_index_iface,node_framework,node_algorithms,node_quantizer_metric toneMint
class node_ailego,node_turbo toneRose
class node_python_binding,node_c_binding,node_plugin,node_examples,node_tools toneIndigo
```

## Components

### Public API

C and Python entry points for host applications.

- [C API](https://github.com/alibaba/zvec/blob/main/src/include/zvec/c_api.h): public api · Primary C surface for embedding zvec in host apps. · `src/include/zvec/c_api.h`
- [Python API](https://github.com/alibaba/zvec/tree/main/python/zvec): binding · Python package wrapping collections, schemas, docs, params, and extensions. · `python/zvec`

### DB Layer

Collection, schema, query, rerank, and SQL orchestration.

- [Collection](https://github.com/alibaba/zvec/blob/main/src/db/collection.cc): db orchestrator · Collection lifecycle and CRUD entry point for the embedded database. · `src/db/collection.cc`
- [Schema & docs](https://github.com/alibaba/zvec/tree/main/src/include/zvec/db): db model · Collection schema, document model, query parameters, and status types. · `src/include/zvec/db`
- [DB common](https://github.com/alibaba/zvec/tree/main/src/db/common): support · Shared config, status, error, resources, and utility code for the DB layer. · `src/db/common`
- [SQL engine](https://github.com/alibaba/zvec/tree/main/src/db/sqlengine): query planner · Parses, analyzes, plans, and executes higher-level hybrid queries. · `src/db/sqlengine`
- [Reranker](https://github.com/alibaba/zvec/blob/main/src/db/reranker/reranker.cc): query refine · Post-retrieval reranking hook used by DB and Python extensions. · `src/db/reranker/reranker.cc`

### Core Engine

Pluggable indexing, search, storage, and segment management.

- [Segments](https://github.com/alibaba/zvec/tree/main/src/db/index/segment): layout · Collection partitioning unit coordinating reads, merges, and index dispatch. · `src/db/index/segment`
- [Vector columns](https://github.com/alibaba/zvec/tree/main/src/db/index/column/vector_column): column index · Vector-column indexing and combined vector retrieval plumbing. · `src/db/index/column/vector_column`
- [Full text](https://github.com/alibaba/zvec/tree/main/src/db/index/column/fts_column): text index · Tokenizer, parser, posting lists, BM25, and phrase/term iterators. · `src/db/index/column/fts_column`
- [Inverted column](https://github.com/alibaba/zvec/tree/main/src/db/index/column/inverted_column): filter index · Scalar and text-like inverted indexing path for hybrid filters. · `src/db/index/column/inverted_column`
- [Storage & WAL](https://github.com/alibaba/zvec/tree/main/src/db/index/storage): persistence · Forward stores, file formats, and write-ahead logging for durability. · `src/db/index/storage`
- [Index framework](https://github.com/alibaba/zvec/tree/main/src/core/interface): abstraction · Common index interfaces, builders, searchers, streamers, reducers, and lifecycle hooks. · `src/core/interface`
- [Framework](https://github.com/alibaba/zvec/tree/main/src/core/framework): orchestration · Core index orchestration, factory, flow, metadata, mapping, and plugin plumbing. · `src/core/framework`
- [Vector families](https://github.com/alibaba/zvec/tree/main/src/core/algorithm): indexes · Built-in vector index families: flat, HNSW, IVF, DiskANN, Vamana, and variants. · `src/core/algorithm`
- [Metric & quantize](https://github.com/alibaba/zvec/tree/main/src/core/quantizer): format adapter · Vector metric conversion, reforming, and mixed-precision normalization. · `src/core/quantizer`

### Perf Library

Low-level math, quantization, and runtime acceleration.

- [ailego](https://github.com/alibaba/zvec/tree/main/src/ailego): math/runtime · Low-level containers, math kernels, threading, CPU detection, and utilities. · `src/ailego`
- [turbo](https://github.com/alibaba/zvec/tree/main/src/turbo): kernel lib · Specialized AVX512 VNNI kernels for quantized search and quantization. · `src/turbo`

### Integration

Bindings, plugins, examples, and tools around the core.

- [Py binding](https://github.com/alibaba/zvec/tree/main/src/binding/python): native bridge · Python extension module exposing the C++ model layer. · `src/binding/python`
- [C binding](https://github.com/alibaba/zvec/tree/main/src/binding/c): native bridge · C wrapper for the exported API. · `src/binding/c`
- [Plugins](https://github.com/alibaba/zvec/tree/main/src/core/plugin): extension · Pluggable index backends such as DiskANN exposed through the core plugin layer. · `src/core/plugin`
- [Examples](https://github.com/alibaba/zvec/tree/main/examples): usage · C and C++ examples showing public API and core usage patterns. · `examples`
- [Tools](https://github.com/alibaba/zvec/tree/main/tools): bench/util · Benchmarking, recall, conversion, and local build utilities. · `tools`

## Connections

- Python API → Py binding: wraps · Python package uses the native binding module.
- Py binding → C API: calls · Python binding ultimately exposes the C/C++ entry surface.
- C binding → C API: exports · C binding implements the exported C API.
- C API → Collection: opens · Public operations create or access collections.
- Collection → Schema & docs: uses · Collections rely on schema, docs, params, and status models.
- Collection → DB common: depends · Collection orchestration uses shared DB infrastructure.
- Collection → SQL engine: queries · Collection query APIs delegate to the SQL/query engine.
- Collection → Segments: organizes · Collections are partitioned and served through segments.
- SQL engine → Segments: plans to · Query plans are lowered to segment-level execution.
- SQL engine → Vector columns: recalls · Vector search plans dispatch into vector column indexes.
- SQL engine → Full text: full-text · Text and hybrid queries use the FTS pipeline.
- SQL engine → Inverted column: filters · Structured and scalar filtering is handled by inverted indexes.
- SQL engine → Reranker: re-ranks · Candidate results can be reranked after retrieval.
- Segments → Storage & WAL: persists · Segments are backed by storage and WAL for durability.
- Segments → Vector columns: hosts · Segments contain column-level vector index state.
- Segments → Full text: hosts · Segments contain text index state and postings.
- Segments → Inverted column: hosts · Segments contain inverted/filter state.
- Vector columns → Index framework: implements · Vector column code uses the shared index abstraction.
- Full text → Storage & WAL: stores · FTS indexing uses persistent stores and merge helpers.
- Inverted column → Storage & WAL: stores · Inverted indexes write through persistence and merge paths.
- Index framework → Framework: adapts · Interface types are orchestrated by the framework layer.
- Framework → Vector families: loads · Framework creates and manages concrete vector families.
- Framework → Plugins: extends · Framework can load plugin-provided index capabilities.
- Vector families → Metric & quantize: normalizes · Algorithms rely on metric and quantization conversion.
- Metric & quantize → ailego: uses · Quantization and metrics build on low-level math/runtime support.
- Vector families → ailego: accelerates · Index implementations use SIMD kernels, math, and utilities.
- turbo → ailego: accelerates · Turbo provides specialized kernels alongside the base runtime library.
- Plugins → Vector families: provides · Plugins contribute concrete index families such as DiskANN.
- Python API → Reranker: extends · Python exposes embedding and rerank extension hooks.
- Examples → C API: demonstrates · Examples show the C-facing API shape.
- Examples → Collection: demonstrates · Examples also cover collection and index workflows.
- Tools → SQL engine: benchmarks · Tools exercise and benchmark query execution paths.
- Tools → Vector families: measures · Tools support recall and performance comparison across indexes.