zvec-rust

Features

Supported Platforms

Architecture

zvec-rust/
├── zvec-sys/ # Low-level FFI bindings to libzvec_c_api
├── zvec/ # Safe, high-level Rust wrapper
└── fuzz/ # Fuzz testing targets

Prerequisites

Option 1: Bundled Prebuilt Library (Zero Setup)

[dependencies]
zvec-rust = "0.7.0"

Option 2: Custom Build

# Build zvec from source
git clone https://github.com/alibaba/zvec.git && cd zvec
mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_C_BINDINGS=ON
make -j$(nproc)
# Point zvec-rust to your custom build
export ZVEC_LIB_DIR=/path/to/zvec/build/lib

make setup # Install dev tools + init git submodule
make zvec-build # Build the zvec C library from submodule
make test-all # Run all tests

Library Resolution Order

Quick Start

use zvec_rust::*;
fn main() -> zvec_rust::Result<()> {
 // 1. Initialize the engine
 initialize(None)?;
 // 2. Define schema
 let schema = CollectionSchema::builder("my_collection")
 // Note 1: use `?` to unwrap the Result returned by FieldSchema::new
 .add_field(FieldSchema::new("id", DataType::String, false, 0)?)
 // Note 2: use `?` to unwrap the Result returned by IndexParams::hnsw
 .add_vector_field(
 "embedding",
 DataType::VectorFp32,
 128,
 IndexParams::hnsw(MetricType::Cosine, 16, 200)?
 )
 .build()?;
 println!("Schema built successfully.");
 // 3. Create and open the collection (the directory will be created if it does not exist)
 // "./data" is the local storage path
 let collection = Collection::create_and_open("./data", &schema, None)?;
 println!(" Collection opened.");
 // 4. Insert data
 let mut doc = Doc::new()?;
 doc.set_pk("doc1");
 doc.add_string("id", "doc1")?;
 // Build a 128-dim vector filled with 0.1
 let vec_data = vec![0.1_f32; 128];
 doc.add_vector_f32("embedding", &vec_data)?;
 // `insert` accepts a slice of &[&Doc]
 collection.insert(&[&doc])?;
 println!("Document inserted.");
 // 5. Vector similarity search
 // Query vector: filled with 0.2
 let query_vec = vec![0.2_f32; 128];
 let query = SearchQuery::new("embedding", &query_vec, 10)?;
 let results = collection.query(&query)?;
 println!("Search Results:");
 for result in &results {
 let pk = result.get_pk().unwrap_or("unknown");
 let score = result.get_score();
 println!(" PK: {}, Score: {:.4}", pk, score);
 }
 // 6. Shutdown the engine
 shutdown()?;
 println!("Test Finished!");
 Ok(())
}

Examples

# Using cargo directly (requires ZVEC_LIB_DIR / DYLD_LIBRARY_PATH)
export DYLD_LIBRARY_PATH=vendor/zvec/build/lib
cargo run --example basic
cargo run --example vector_search

API Overview

Initialization

let config = ConfigBuilder::new()
 .memory_limit(1024 * 1024 * 1024)
 .num_threads(4)
 .enable_console_log(true)
 .build();
initialize(Some(&config))?;

jieba FTS tokenizer dictionary

initialize(None)?; // jieba dict auto-discovered and registered
let schema = CollectionSchema::builder("articles")
 .add_field(FieldSchema::new("id", DataType::String, false, 0)?)
 .add_indexed_field("content", DataType::String,
 IndexParams::fts(Some("jieba"), None, None)?)
 .build()?;

Schema Definition

let schema = CollectionSchema::builder("name")
 .add_field(FieldSchema::new("field", DataType::String, false, 0)?)
 .add_vector_field("vec", DataType::VectorFp32, 128,
 IndexParams::hnsw(MetricType::Cosine, 16, 200)?)
 .build()?;

Collection Operations

Document Operations

let mut doc = Doc::new()?;
doc.set_pk("my_pk");
doc.add_string("name", "value")?;
doc.add_i64("count", 42)?;
doc.add_vector_f32("embedding", &[0.1, 0.2, 0.3])?;
// Getters return `Result<Option<T>>` — `?` only unwraps the Result.
// Use `unwrap_or_default()` / `expect(..)` etc. to handle the Option.
let name: Option<String> = doc.get_string("name")?;
let count: Option<i64> = doc.get_i64("count")?;

Vector Query

// Simple query
let query = SearchQuery::new("embedding", &query_vec, 10)?;
// Builder pattern with filters
let query = SearchQuery::builder()
 .field_name("embedding")
 .vector(&query_vec)
 .topk(10)
 .filter("category = 'tech'")
 .output_fields(&["id", "name"])
 .build()?;

Multi-Query (Hybrid Search)

// FTS + vector hybrid search with RRF reranking
let mut sub_vec = SubQuery::new()?;
sub_vec.set_field_name("embedding")?;
sub_vec.set_query_vector(&query_vec)?;
sub_vec.set_num_candidates(50)?;
let mut fts = Fts::new()?;
fts.set_match_string("Rust vector database")?;
let mut sub_fts = SubQuery::new()?;
sub_fts.set_field_name("content")?;
sub_fts.set_fts(&fts)?;
sub_fts.set_num_candidates(50)?;
let mut mq = MultiQuery::new()?;
mq.set_topk(10)?;
mq.set_rerank_rrf(60)?; // rank constant for RRF
mq.add_sub_query(&sub_vec)?;
mq.add_sub_query(&sub_fts)?;
let results = collection.multi_query(&mq)?;
// Weighted reranking
mq.set_rerank_weighted(&[0.7, 0.3])?; // weights per sub-query

Supported Types

Index Types

Testing

# Using Makefile (recommended — auto-detects library paths)
make test-unit # Unit tests (no C library required)
make test-integration # Integration tests (requires C library)
make test-all # All tests (unit + integration + doc)
# Using cargo directly (requires ZVEC_LIB_DIR / DYLD_LIBRARY_PATH)
cargo test --lib
cargo test --test integration_test
# Fuzz tests (requires nightly)
cargo install cargo-fuzz
cargo +nightly fuzz run fuzz_types -- -max_total_time=60
# Benchmarks
make bench
# Code coverage
cargo install cargo-llvm-cov
./scripts/coverage.sh --html

Keeping in Sync with zvec Core

Contributing

License