a3s_vec/
lib.rs

1//! `a3s-vec` is A3S's native Rust in-process vector database.
2//!
3//! The crate provides the collection, document, schema, query, index, and
4//! durability primitives needed by an embedded vector store.  It follows the
5//! zvec Rust API vocabulary while keeping the implementation free of a C/C++
6//! runtime dependency, which makes the same source usable on Apple Silicon,
7//! current Intel macOS (deployment target 15.0), Linux, and Windows. macOS 12
8//! Monterey Intel is unsupported.
9//!
10//! A collection's document snapshot and WAL are authoritative. Flat queries
11//! execute against that snapshot; revision-tagged HNSW, IVF, metric-aware
12//! Vamana, and product-quantized `DiskANN` generations select bounded
13//! candidates before exact re-ranking. Each Vamana/DiskANN base also has an A3S-native,
14//! sector-aligned recovery sidecar. Native
15//! numeric vector encodings are preserved at rest and remain distinct from index-only
16//! FP16/INT8/INT4 scalar quantization. Revisioned scalar and full-text indexes
17//! accelerate structured and lexical retrieval, including Unicode n-grams,
18//! ordered token filters, boolean groups, required/prohibited clauses, and
19//! wildcard/fuzzy/range terms, boosts, and ordered phrase proximity. HNSW and
20//! IVF also provide multi-bit `RaBitQ` families with exact re-ranking. `DiskANN`
21//! uses deterministic PQ training, ADC graph traversal, and a typed choice of
22//! positioned reads or a validated immutable anonymous mmap snapshot. With the
23//! `async` feature, query, multi-query, and group-by entry points run that same
24//! work on Tokio's blocking pool. Writable collections can also opt into one
25//! explicitly owned standard-thread maintenance scheduler, while public health
26//! snapshots distinguish authoritative revision failures from derived-index
27//! degradation and normal WAL checkpoint lag. Native async file reads and
28//! direct file-backed mmap remain explicit future optimizations.
29//!
30//! Filter parsing, tokenization, and index quantization live in this crate.
31//! They are not part of the stable A3S API:
32//!
33//! ```compile_fail
34//! use a3s_vec::core;
35//! ```
36
37mod collection;
38mod config;
39mod doc;
40mod embedding;
41mod error;
42mod filter;
43mod index;
44mod iterator;
45mod multi_query;
46mod query;
47mod schema;
48mod score_f64;
49mod stats;
50mod storage;
51mod storage_ceilings;
52mod text;
53mod types;
54
55pub use collection::{
56    Collection, CollectionHealth, CollectionHealthStatus, CollectionMaintenanceHealth,
57    CollectionMaintenanceOptions, CollectionMaintenancePhase, CollectionMaintenanceRuntime,
58    CollectionOptions, CollectionResourceLimits, CollectionStats, DocWriteResult, IndexStat,
59    WriteResult,
60};
61pub use config::{
62    check_version, default_config, initialize, is_initialized, shutdown, version, version_major,
63    version_minor, version_patch, ConfigBuilder, Durability, IoBackend,
64};
65pub use doc::{Doc, FieldValue, VectorValue};
66pub use embedding::{DenseEmbedding, EmbeddingInput, QueryExecutor, SparseEmbedding};
67pub use error::{Error, ErrorCode, Result};
68pub use iterator::DocIterator;
69pub use multi_query::{MultiQuery, RerankMethod, SubQuery};
70pub use query::{
71    DiskannQueryParams, FlatQueryParams, Fts, FtsQueryParams, GroupBySearchQuery, HnswQueryParams,
72    IvfQueryParams, IvfRabitqQueryParams, SearchQuery, SearchQueryBuilder, VectorQuery,
73};
74pub use schema::{
75    AddColumnOption, AlterColumnOption, CollectionSchema, CollectionSchemaBuilder,
76    DiskANNIndexParam, DiskAnnIndexParam, FieldSchema, FlatIndexParam, FtsIndexParam,
77    HnswIndexParam, IVFIndexParam, IndexParams, IndexParamsBuilder, InvertIndexParam,
78    IvfIndexParam, IvfRabitqIndexParam, VamanaIndexParam, VectorSchema,
79};
80pub use stats::StatsSnapshot;
81pub use storage_ceilings::{
82    StorageCeilings, DEFAULT_DISKANN_FILE_BYTES, DEFAULT_INDEX_CACHE_BYTES, DEFAULT_SNAPSHOT_BYTES,
83    DEFAULT_WAL_REPLAY_BYTES, INDEX_CACHE_FILE_OVERHEAD_BYTES,
84};
85pub use types::{DataType, DocOperator, IndexType, MetricType, QuantizeType};
86
87/// Convenient import for the common collection workflow.
88pub mod prelude {
89    pub use crate::{
90        initialize, is_initialized, version, Collection, CollectionMaintenanceOptions,
91        CollectionOptions, CollectionResourceLimits, CollectionSchema, ConfigBuilder, DataType,
92        Doc, DocIterator, Error, ErrorCode, FieldSchema, IndexParams, IoBackend, MetricType,
93        MultiQuery, QuantizeType, Result, SearchQuery, StorageCeilings, VectorSchema, WriteResult,
94    };
95}
96
97#[cfg(test)]
98mod tests {
99    use super::*;
100
101    #[test]
102    fn public_version_is_nonempty() {
103        assert!(!version().is_empty());
104    }
105}
a3s_vec/lib.rs

a3s_vec/
lib.rs
