Crate zvec 

Rust bindings to zvec, Alibaba’s lightweight in-process vector database.

At a glance

• Raw FFI in sys — every zvec C API symbol, generated by bindgen from a pinned c_api.h.
• Safe, idiomatic wrappers at the crate root covering the full public C API: CollectionSchema / FieldSchema, IndexParams (and builder sugar via FieldSchemaBuilder), VectorQuery / GroupByVectorQuery, Collection (create/open/flush/optimize + DDL + DML + DQL), Doc / DocRef, and CollectionStats.
• Batteries-included retrieval helpers: HybridSearch for fused multi-query search, and rerank::RrfReRanker / rerank::WeightedReRanker for standalone result fusion.
• Feature-gated niceties: async, JSON ingest, half-precision vectors, a derive macro, and a zero-setup bundled install path.

Optional cargo features

Feature	Adds
bundled	Fetches upstream’s PyPI wheel at build time — no external zvec setup needed.
derive	#[derive(IntoDoc)] — struct-to-Doc conversion (see IntoDoc).
tokio	AsyncCollection — every op wrapped in tokio::task::spawn_blocking.
serde-json	Doc::from_json — build a Doc from a serde_json::Value + schema.
half	Doc::add_vector_fp16, DocRef::get_vector_fp16, VectorQuery::set_query_vector_fp16 taking &[half::f16].
pkg-config	Locate libzvec_c_api via pkg-config (in addition to env-var discovery).

Install paths

build.rs locates a prebuilt libzvec_c_api, in order:

1. ZVEC_LIB_DIR — explicit directory.
2. ZVEC_ROOT — install prefix; uses $ZVEC_ROOT/lib (+ lib64).
3. --features bundled — download + extract the PyPI wheel.
4. pkg-config (if the pkg-config feature is on).
5. System linker defaults.

Set ZVEC_STATIC=1 for static linking. ZVEC_INCLUDE_DIR / ZVEC_ROOT redirect bindgen at an installed header instead of the one vendored here.

Quickstart

use zvec::{Collection, CollectionSchema, Doc, FieldSchema, MetricType, VectorQuery};

// Builder sugar for schemas:
let schema = CollectionSchema::builder("docs")
    .field(FieldSchema::string("id").invert_index(true, false))
    .field(
        FieldSchema::vector_fp32("embedding", 3)
            .hnsw(16, 200)
            .metric(MetricType::Cosine),
    )
    .build()?;

let collection = Collection::create_and_open("./my_coll", &schema, None)?;

let mut doc = Doc::new()?;
doc.set_pk("doc1")?;
doc.add_string("id", "doc1")?;
doc.add_vector_fp32("embedding", &[0.1, 0.2, 0.3])?;
collection.insert(&[&doc])?;
collection.flush()?;

let q = VectorQuery::builder()
    .field("embedding")
    .vector_fp32(&[0.1, 0.2, 0.3])
    .topk(10)
    .build()?;
for row in collection.query(&q)?.iter() {
    println!("{:?} score={}", row.pk_copy(), row.score());
}

More end-to-end recipes live under examples/: semantic_search, hybrid_search, json_ingest, and the Rust port of basic_example.c.

Thread safety

• Collection is Send + Sync. Sharing one across threads is just Arc<Collection>; no dedicated SharedCollection type is needed.
• Pure builders / config types (CollectionSchema, FieldSchema, IndexParams, HnswQueryParams, CollectionOptions, …) are Send + Sync.
• Types with mutable C-side state and no documented thread-safe reads (Doc, VectorQuery, GroupByVectorQuery, DocSet) are Send only.

use std::sync::Arc;
use std::thread;
let collection = Arc::new(Collection::create_and_open("./coll", &schema, None)?);
let handles: Vec<_> = (0..4)
    .map(|_| {
        let c = Arc::clone(&collection);
        thread::spawn(move || c.flush())
    })
    .collect();
for h in handles { let _ = h.join(); }

Where to go next

• Collection — lifecycle, DDL, DML, DQL.
• HybridSearch — fused multi-query search.
• rerank — reciprocal-rank and weighted fusion over arbitrary Vec<Hit> inputs.
• IntoDoc (feature derive) — #[derive(IntoDoc)] to skip manual add_* calls.
• AsyncCollection (feature tokio) — async wrapper for tokio users.
• Doc::from_json (feature serde-json) — JSON → Doc bridge.

Modules

rerank

Result re-ranking / fusion helpers.

sys

Raw FFI bindings to the zvec C API.

Structs

AsyncCollectiontokio

Tokio-friendly handle to a Collection. Cheap to clone.

Collection

CollectionOptions

CollectionSchema

CollectionSchemaBuilder

Builder for CollectionSchema. Accumulates pending fields and options; surfaces any validation errors at Self::build.

CollectionStats

Config

Global zvec runtime configuration, passed to initialize.

Doc

Owning document.

DocRef

Non-owning document reference (e.g. rows returned from a query).

DocSet

Result set returned by Collection::query or Collection::fetch.

FieldSchema

FieldSchemaBuilder

Builder for FieldSchema. Constructed via the type-specific associated functions (FieldSchema::string, ::vector_fp32, …).

FieldSchemaRef

Non-owning borrow of a field schema returned by schema accessors.

FlatQueryParams

GroupByVectorQuery

HnswQueryParams

HybridSearch

Builder that runs a set of VectorQuerys and fuses their results.

IndexParams

IvfQueryParams

LogConfig

Logging sink + level configuration.

VectorQuery

VectorQueryBuilder

Builder for VectorQuery. Covers every knob on the query except set_query_params (the untyped escape hatch); HNSW / IVF / Flat parameters still go through their respective builders and .params(...).

WriteResult

Per-document status returned by the *_with_results batch write APIs.

WriteSummary

Result summary returned by batch write APIs.

ZvecError

Error returned by fallible safe wrappers over the zvec C API.

Enums

DataType

Scalar, vector, and array element types recognised by zvec.

DocOperator

Document operator semantics carried on a crate::doc::Doc.

ErrorCode

Strongly-typed mirror of sys::zvec_error_code_t.

IndexType

Index algorithm families.

LogLevel

Log level used by crate::config::LogConfig.

LogType

Log sink type.

MetricType

Distance metric used by vector indexes.

QuantizeType

Optional post-quantization applied to vectors before indexing.

Traits

FromDoc

Reconstruct Self from a DocRef.

IntoDoc

Convert &self into a freshly-allocated Doc.

Functions

check_version

Returns true if the linked zvec library is at least major.minor.patch.

clear_last_error

Clear the current thread-local last-error slot.

initialize

Initialize the zvec library.

is_initialized

Returns whether initialize has been called successfully.

shutdown

Tear down any process-global state created by initialize.

version

Returns the full version string reported by the linked zvec library.

version_major

version_minor

version_patch

Type Aliases

Result

Convenience alias for Result<T, ZvecError> used throughout the crate.

Derive Macros

FromDocderive

Re-exports of the derive macros from the zvec-derive crate.

IntoDocderive

Re-exports of the derive macros from the zvec-derive crate.