Struct Database 

pub struct Database { /* private fields */ }

Database instance managing collections and storage.

Lifecycle

Database::open() automatically loads all previously created collections from disk. There is no need to call load_collections() separately.

Extension (Premium)

Use Database::open_with_observer to inject a DatabaseObserver implementation from velesdb-premium without modifying this crate.

Implementations

impl Database

pub fn create_collection( &self, name: &str, dimension: usize, metric: DistanceMetric, ) -> Result<()>

Creates a new collection with the specified parameters.

Arguments

• name - Unique name for the collection
• dimension - Vector dimension (e.g., 768 for many embedding models)
• metric - Distance metric to use for similarity calculations

Errors

• Returns Error::CollectionExists if a collection with the same name already exists.
• Returns an error if the directory cannot be created or storage initialization fails.

Examples

let db = Database::open("./data")?;
db.create_collection("documents", 768, DistanceMetric::Cosine)?;

pub fn create_collection_with_options( &self, name: &str, dimension: usize, metric: DistanceMetric, storage_mode: StorageMode, ) -> Result<()>

Creates a new collection with custom storage options.

Errors

Returns an error if a collection with the same name already exists.

pub fn get_collection(&self, name: &str) -> Option<Collection>

👎Deprecated since 2.0.0:

Use get_vector_collection(), get_graph_collection(), or get_metadata_collection()

Gets a reference to a collection by name.

Returns

Returns None if the collection does not exist.

pub fn collection_write_generation(&self, name: &str) -> Option<u64>

Returns the write generation for a named collection, if it exists.

pub fn list_collections(&self) -> Vec<String>

Lists all collection names in the database.

Includes collections created via any typed API (vector, graph, metadata).

pub fn delete_collection(&self, name: &str) -> Result<()>

Deletes a collection by name.

Errors

Returns an error if the name is invalid or the collection does not exist in any registry.

pub fn create_collection_typed( &self, name: &str, collection_type: &CollectionType, ) -> Result<()>

Creates a new collection with a specific type (Vector, Graph, or MetadataOnly).

Errors

Returns an error if a collection with the same name already exists.

pub fn update_guardrails(&self, limits: &QueryLimits)

Propagates updated query limits to all active collections.

pub fn collection_diagnostics( &self, name: &str, ) -> Result<CollectionDiagnostics>

Returns diagnostics for a named collection.

Errors

Returns Error::CollectionNotFound if the collection does not exist.

impl Database

pub fn create_graph_collection( &self, name: &str, schema: GraphSchema, ) -> Result<()>

Creates a new graph collection.

Errors

Returns an error if a collection with the same name already exists.

pub fn create_graph_collection_with_embeddings( &self, name: &str, schema: GraphSchema, dimension: usize, metric: DistanceMetric, ) -> Result<()>

Creates a new graph collection with node embeddings.

Unlike create_graph_collection, this variant configures a vector dimension and distance metric so that nodes can store embeddings and support similarity search.

Errors

Returns an error if a collection with the same name already exists.

pub fn get_graph_collection(&self, name: &str) -> Option<GraphCollection>

Returns a GraphCollection by name.

Checks the typed registry first. Falls back to opening from disk if the collection was not registered in-memory (e.g. after a restart or when the collection was auto-created by a graph handler). The instance is cached into the registry so subsequent calls are free.

Returns None if the collection does not exist on disk.

impl Database

pub fn create_metadata_collection(&self, name: &str) -> Result<()>

Creates a new metadata-only collection.

Errors

Returns an error if a collection with the same name already exists.

pub fn get_metadata_collection(&self, name: &str) -> Option<MetadataCollection>

Returns a MetadataCollection by name.

Checks the typed registry first. Falls back to opening from disk for collections created before the typed API existed or after a restart. The instance is cached to avoid repeated disk reads.

Returns None if the collection does not exist on disk.

impl Database

pub fn load_collections(&self) -> Result<()>

Loads existing collections from disk.

Deprecation note

This method is called automatically by Database::open. There is no need to call it manually. It is kept public only for backward compatibility with code that relied on the old two-step pattern.

Errors

Returns an error if collection directories cannot be read.

pub fn flush_all(&self) -> usize

Flushes all collections including vectors.idx serialization.

Issue #423: Uses flush_full() to ensure the vector index file is up-to-date, avoiding a full WAL replay on the next startup. This is the correct method for graceful shutdown.

Best-effort: logs warnings for individual flush failures but continues flushing remaining collections. Returns the count of failures.

The legacy collections registry is not iterated because it shares the same Arc’d inner storage as the typed registries. Flushing both would double-flush every collection, causing redundant I/O and potentially double-counting failures.

impl Database

pub fn build_plan_key(&self, query: &Query) -> PlanKey

Builds a deterministic cache key for a query (CACHE-02).

Serialises the query to canonical JSON (object keys sorted recursively), reads the current schema_version, and gathers per-collection write_generation counters (sorted by collection name) to form a PlanKey.

Why canonical JSON instead of Debug

format!("{query:?}") is non-deterministic when the Query AST contains HashMap-backed fields (FusionConfig::params, TrainStatement::params) because HashMap iteration order is not guaranteed across invocations. Canonical JSON with sorted object keys is stable and produces the same byte sequence for logically identical queries.

pub fn explain_query(&self, query: &Query) -> Result<QueryPlan>

Returns the query plan for a query, with cache status populated (CACHE-02).

If the plan is cached, returns it with cache_hit: Some(true) and plan_reuse_count set. Otherwise generates a fresh plan with cache_hit: Some(false).

Design decision: explain_query does not populate the cache

explain_query intentionally does not insert a new plan into the compiled plan cache. EXPLAIN is a diagnostic operation; allowing it to influence cache state would make cache metrics (hit/miss ratios, plan_reuse_count) unreliable because EXPLAIN calls would be indistinguishable from real execution hits. Only execute_query is authorised to write to the cache.

Errors

Returns an error if the query is invalid.

pub fn execute_query( &self, query: &Query, params: &HashMap<String, Value>, ) -> Result<Vec<SearchResult>>

Executes a VelesQL query with database-level JOIN resolution.

This method resolves JOIN target collections from the database registry and executes JOIN runtime in sequence. Query plans are cached and reused for identical queries against unchanged collections (CACHE-02).

Errors

Returns an error if the base collection or any JOIN collection is missing.

impl Database

pub fn analyze_collection(&self, name: &str) -> Result<CollectionStats>

Analyzes a collection, caches stats, and persists them to disk.

Errors

Returns an error if the name is invalid, the collection does not exist, analysis fails, or stats cannot be serialized and written to disk.

pub fn get_collection_stats( &self, name: &str, ) -> Result<Option<CollectionStats>>

Returns cached statistics when available, loading from disk if present.

Errors

Returns an error if the name is invalid, or the on-disk stats file exists but cannot be read or deserialized.

impl Database

pub fn create_vector_collection( &self, name: &str, dimension: usize, metric: DistanceMetric, ) -> Result<()>

Creates a new vector collection.

Errors

Returns an error if a collection with the same name already exists.

pub fn create_vector_collection_with_options( &self, name: &str, dimension: usize, metric: DistanceMetric, storage_mode: StorageMode, ) -> Result<()>

Creates a new vector collection with custom storage options.

Errors

Returns an error if a collection with the same name already exists.

pub fn create_vector_collection_with_hnsw( &self, name: &str, dimension: usize, metric: DistanceMetric, storage_mode: StorageMode, m: Option<usize>, ef_construction: Option<usize>, ) -> Result<()>

Creates a new vector collection with custom HNSW parameters.

When m or ef_construction are Some, those values override the dimension-based auto-tuned defaults from [HnswParams::auto].

Errors

Returns an error if a collection with the same name already exists.

pub fn get_vector_collection(&self, name: &str) -> Option<VectorCollection>

Returns a VectorCollection by name.

Checks the typed registry first. If not found there, falls back to opening the collection directory from disk (e.g. for collections created via the legacy create_collection API that were not registered in the typed registry). The opened instance is cached back into the registry so subsequent calls avoid the disk round-trip.

Returns None if the collection does not exist on disk.

impl Database

pub fn open<P: AsRef<Path>>(path: P) -> Result<Self>

Opens or creates a database, automatically loading all existing collections.

This replaces the previous open() + load_collections() two-step pattern. The new open() is a strict auto-load: all config.json directories under path are loaded on startup.

Errors

Returns an error if the directory cannot be created or accessed.

pub fn open_with_observer<P: AsRef<Path>>( path: P, observer: Arc<dyn DatabaseObserver>, ) -> Result<Self>

Opens a database with a DatabaseObserver (used by velesdb-premium).

The observer receives lifecycle hooks for every collection operation, enabling RBAC, audit logging, multi-tenant routing, etc.

Errors

Returns an error if the directory cannot be created or accessed.

pub fn data_dir(&self) -> &Path

Returns the path to the data directory.

pub fn schema_version(&self) -> u64

Returns the current DDL schema version counter.

pub fn plan_cache(&self) -> &CompiledPlanCache

Returns a reference to the compiled query plan cache.

pub fn notify_upsert(&self, collection: &str, point_count: usize)

Notifies the observer that points were upserted into a collection.

Caller contract: this method is NOT called automatically by Database internals. HTTP handlers and SDK bindings are responsible for calling it after a successful upsert, passing the number of points written. Forgetting to call it means the observer receives no upsert events for that operation.

No-op when no observer is registered.

pub fn notify_query(&self, collection: &str, duration_us: u64)

Notifies the observer that a query was executed, with its duration.

Caller contract: this method is NOT called automatically by Database::execute_query. Callers must measure the wall-clock duration themselves (e.g. std::time::Instant::now() before the call) and invoke this method afterwards with the elapsed microseconds.

No-op when no observer is registered.