zvec 0.1.0

Rust bindings to zvec, an in-process vector database by Alibaba.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179

//! 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
//!
//! ```no_run
//! # fn main() -> zvec::Result<()> {
//! 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());
//! }
//! # Ok(())
//! # }
//! ```
//!
//! More end-to-end recipes live under [`examples/`](https://github.com/oly-wan-kenobi/zvec-rs/tree/main/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.
//!
//! ```no_run
//! # fn main() -> zvec::Result<()> {
//! use std::sync::Arc;
//! use std::thread;
//! # use zvec::{Collection, CollectionSchema};
//! # let schema: CollectionSchema = unreachable!();
//! 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(); }
//! # Ok(())
//! # }
//! ```
//!
//! # 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.
//!
//! [zvec]: https://github.com/alibaba/zvec

#![cfg_attr(docsrs, feature(doc_cfg))]

pub mod sys;

#[cfg(feature = "tokio")]
mod async_collection;
mod builder;
mod collection;
mod config;
mod doc;
mod error;
mod ffi_util;
mod from_doc;
mod hybrid;
mod index_params;
mod into_doc;
mod options;
mod query;
mod query_params;
pub mod rerank;
mod schema;
#[cfg(feature = "serde-json")]
mod serde_json_bridge;
mod stats;
mod types;
mod version;

#[cfg(feature = "tokio")]
#[cfg_attr(docsrs, doc(cfg(feature = "tokio")))]
pub use async_collection::AsyncCollection;
pub use builder::{CollectionSchemaBuilder, FieldSchemaBuilder, VectorQueryBuilder};
pub use collection::{Collection, DocSet, WriteResult, WriteSummary};
pub use config::{initialize, is_initialized, shutdown, Config, LogConfig};
pub use doc::{Doc, DocRef};
pub use error::{clear_last_error, ErrorCode, Result, ZvecError};
pub use from_doc::FromDoc;
pub use hybrid::HybridSearch;
pub use index_params::IndexParams;
pub use into_doc::IntoDoc;
pub use options::CollectionOptions;
pub use query::{GroupByVectorQuery, VectorQuery};
pub use query_params::{FlatQueryParams, HnswQueryParams, IvfQueryParams};
pub use schema::{CollectionSchema, FieldSchema, FieldSchemaRef};
pub use stats::CollectionStats;
pub use types::{DataType, DocOperator, IndexType, LogLevel, LogType, MetricType, QuantizeType};
pub use version::{check_version, version, version_major, version_minor, version_patch};

/// Re-exports of the derive macros from the `zvec-derive` crate.
///
/// Available with the `derive` cargo feature.
#[cfg(feature = "derive")]
#[cfg_attr(docsrs, doc(cfg(feature = "derive")))]
pub use zvec_derive::{FromDoc, IntoDoc};