Crate git_vdb 

A deterministic, Git-native embedded vector database.

git-vdb stores vectors, payloads, metadata, and search indexes as immutable Git objects. A canonical Git tree identifies the complete database state; commits and refs are an optional naming and history layer above that state. Equivalent configuration and points therefore produce the same root tree, independent of insertion order, repository path, history, or timestamps.

Two APIs expose the same storage engine:

• SnapshotEngine works directly with immutable root IDs and never creates commits or updates refs.
• Database and Collection manage named collections under refs/git-vdb/collections/*, including history and compare-and-swap writes.

Immutable snapshot example

use git_vdb::{CollectionConfig, Point, Query, SnapshotEngine};

let engine = SnapshotEngine::ephemeral()?;
let snapshot = engine.build(
    CollectionConfig::new(2),
    vec![
        Point::new("east", [1.0, 0.0]),
        Point::new("north", [0.0, 1.0]),
    ],
)?;

let result = snapshot.query(Query::exact([0.9, 0.1], 1))?;
assert_eq!(result.points[0].id.to_string(), "east");
assert_eq!(result.root, snapshot.root());

Semantics and compatibility

Exact cosine search scores every eligible point. Approximate search uses a deterministic LSH index and may underfill or omit globally better points when probe or candidate limits are exhausted; QueryResult::stats reports the work performed. Reads and validation never advance refs. Named writes create immutable objects first and then atomically compare-and-swap the collection ref, so Error::StaleRoot cannot silently overwrite a concurrent writer.

The crate’s semantic version and its persisted format version are separate compatibility boundaries. Existing format-version-1 roots remain canonical regardless of physical Git packing.

Re-exports

pub use adapter::Collection;

pub use adapter::Database;

pub use model::CollectionConfig;

pub use model::CollectionInfo;

pub use model::Condition;

pub use model::CountResult;

pub use model::DeleteSelector;

pub use model::DiffResult;

pub use model::Distance;

pub use model::Filter;

pub use model::GetRequest;

pub use model::GetResult;

pub use model::HistoryEntry;

pub use model::IndexConfig;

pub use model::JsonObject;

pub use model::MatchValue;

pub use model::ObjectId;

pub use model::ObjectStats;

pub use model::Point;

pub use model::PointId;

pub use model::Query;

pub use model::QueryMode;

pub use model::QueryParams;

pub use model::QueryResult;

pub use model::QueryStats;

pub use model::Range;

pub use model::Record;

pub use model::ScoredPoint;

pub use model::SnapshotInfo;

pub use model::SnapshotMutation;

pub use model::ValidationReport;

pub use model::WriteResult;

pub use snapshot::Snapshot;

pub use snapshot::SnapshotEngine;

Modules

adapter

Named collections backed by Git commits and compare-and-swap refs.

format

The normative persisted format-version-1 specification.

model

Public request, response, configuration, filtering, and mutation types.

snapshot

Ref-free immutable snapshot construction, mutation, query, and validation.

snapshots

Design notes for immutable root snapshots and named collection history.

Enums

Error

An error returned by a git-vdb operation.

Type Aliases

Result

The result type returned by git-vdb operations.