Crate a3s_vec 

a3s-vec is A3S’s native Rust in-process vector database.

The crate provides the collection, document, schema, query, index, and durability primitives needed by an embedded vector store. It follows the zvec Rust API vocabulary while keeping the implementation free of a C/C++ runtime dependency, which makes the same source usable on Apple Silicon, current Intel macOS (deployment target 15.0), Linux, and Windows. macOS 12 Monterey Intel is unsupported.

A collection’s document snapshot and WAL are authoritative. Flat queries execute against that snapshot; revision-tagged HNSW, IVF, metric-aware Vamana, and product-quantized DiskANN generations select bounded candidates before exact re-ranking. Each Vamana/DiskANN base also has an A3S-native, sector-aligned recovery sidecar. Native numeric vector encodings are preserved at rest and remain distinct from index-only FP16/INT8/INT4 scalar quantization. Revisioned scalar and full-text indexes accelerate structured and lexical retrieval, including Unicode n-grams, ordered token filters, boolean groups, required/prohibited clauses, and wildcard/fuzzy/range terms, boosts, and ordered phrase proximity. HNSW and IVF also provide multi-bit RaBitQ families with exact re-ranking. DiskANN uses deterministic PQ training, ADC graph traversal, and a typed choice of positioned reads or a validated immutable anonymous mmap snapshot. With the async feature, query, multi-query, and group-by entry points run that same work on Tokio’s blocking pool. Writable collections can also opt into one explicitly owned standard-thread maintenance scheduler, while public health snapshots distinguish authoritative revision failures from derived-index degradation and normal WAL checkpoint lag. Native async file reads and direct file-backed mmap remain explicit future optimizations.

Filter parsing, tokenization, and index quantization live in this crate. They are not part of the stable A3S API:

use a3s_vec::core;

Modules

prelude

Convenient import for the common collection workflow.

Structs

AddColumnOption

AlterColumnOption

Collection

Cheap, cloneable, thread-safe handle to one collection.

CollectionHealth

Machine-readable collection readiness and checkpoint-lag snapshot.

CollectionMaintenanceHealth

Point-in-time diagnostics for one maintenance schedule.

CollectionMaintenanceOptions

Periodic schedule for one explicitly owned collection maintenance worker.

CollectionMaintenanceRuntime

Owner of the standard-thread worker that periodically rebuilds derived indexes and checkpoints authoritative state.

CollectionOptions

Supported options for creating or opening a collection.

CollectionResourceLimits

Collection-local logical resource budgets.

CollectionSchema

Collection schema containing scalar and vector fields.

CollectionSchemaBuilder

Fluent collection schema builder.

CollectionStats

Public collection statistics (the fields used by the official SDK are kept first; additional counters are additive).

ConfigBuilder

Supported process-wide durability and sidecar-I/O configuration.

DiskAnnIndexParam

DiskANN/Vamana build parameters.

DiskannQueryParams

Doc

A typed document. BTreeMap gives deterministic snapshots and tie-breaks.

DocIterator

DocWriteResult

Per-document outcome in a batch write.

Error

An error returned by a3s-vec.

FieldSchema

Schema for one field.

FlatIndexParam

Exact flat index parameters.

FlatQueryParams

Fts

FtsIndexParam

Full-text index parameters.

FtsQueryParams

Full-text query controls.

GroupBySearchQuery

Group-by vector query payload.

HnswIndexParam

HNSW build parameters.

HnswQueryParams

IVFIndexParam

IVF build parameters.

IndexParams

Serializable index configuration.

IndexParamsBuilder

Fluent index-parameter builder for callers that prefer typed construction.

IndexStat

InvertIndexParam

Scalar inverted-index parameters.

IvfQueryParams

IvfRabitqIndexParam

IVF RaBitQ build parameters.

IvfRabitqQueryParams

MultiQuery

A collection of sub-queries fused into one ranked result.

SearchQuery

A single dense, sparse, binary, id-based, or FTS query.

SearchQueryBuilder

Fluent builder matching the official SDK’s naming.

StatsSnapshot

StorageCeilings

Explicit ceilings for durable corpus artifacts.

SubQuery

A branch in a MultiQuery.

VamanaIndexParam

Vamana graph parameters. DiskANN uses the same graph with a disk layout.

VectorSchema

Explicit vector schema (also useful to adapters that keep vectors separate).

WriteResult

Result of a batch write.

Enums

CollectionHealthStatus

Readiness assessment for one collection handle.

CollectionMaintenancePhase

Lifecycle phase of an explicitly owned maintenance worker.

DataType

Data type of a collection field.

DocOperator

DML operation kind used by write-ahead records and telemetry.

Durability

WAL acknowledgement policy.

EmbeddingInput

Input accepted by an embedding provider.

ErrorCode

Stable status categories exposed by the collection API.

FieldValue

Scalar and array field values accepted by a collection.

IndexType

Index implementation selected for a field.

IoBackend

Query-time backend for validated derived index sidecars.

MetricType

Similarity metric. Search scores are always ordered from high to low; L2 is represented as negative squared distance at the API boundary.

QuantizeType

Scalar/vector quantization mode.

RerankMethod

Reranking strategy used to fuse branch results.

VectorValue

Dense and sparse vector payloads.

Constants

DEFAULT_DISKANN_FILE_BYTES

Default DiskANN sidecar file ceiling (512 MiB).

DEFAULT_INDEX_CACHE_BYTES

Default derived-index-cache payload ceiling (8 GiB).

DEFAULT_SNAPSHOT_BYTES

Default document-snapshot write/recovery ceiling (8 GiB).

DEFAULT_WAL_REPLAY_BYTES

Default committed WAL replay ceiling (8 GiB).

INDEX_CACHE_FILE_OVERHEAD_BYTES

Extra allowance for the on-disk index-cache framing beyond the payload.

Traits

DenseEmbedding

Dense embedding provider. Implementations should be pure with respect to the collection; retries and network policy belong in the adapter.

QueryExecutor

Optional convenience for executing a query after embedding text.

SparseEmbedding

Sparse embedding provider.

Functions

check_version

default_config

Returns a fresh builder with portable defaults.

initialize

Sets the process defaults captured by collections created or opened after this call. Existing collection handles retain their resolved configuration.

is_initialized

Returns whether the runtime has been initialized explicitly.

shutdown

Resets process defaults and marks the runtime uninitialized.

version

Version of the native Rust implementation.

version_major

version_minor

version_patch

Type Aliases

DiskANNIndexParam

IvfIndexParam

Result

Specialized result type for all public operations.

VectorQuery

Compatibility alias used by the zvec vocabulary.