Struct VelesDatabase 

pub struct VelesDatabase { /* private fields */ }

VelesDB database instance.

Thread-safe handle to a VelesDB database. Can be shared across threads.

Implementations

impl VelesDatabase

pub fn open(path: String) -> Result<Arc<Self>, VelesError>

Opens or creates a database at the specified path.

Arguments

• path - Path to the database directory (will be created if needed)

Errors

Returns an error if the path is invalid or cannot be accessed.

pub fn open_with_observer( path: String, observer: Arc<dyn MobileObserver>, ) -> Result<Arc<Self>, VelesError>

Opens or creates a database with a read-path MobileObserver attached.

The observer is consulted before every governed read (dense / text / hybrid / sparse / multi-query search and VelesQL SELECT / MATCH): returning MobileAccessDecision::Deny aborts the read with that message and zero results, MobileAccessDecision::Allow runs it unmodified. This is the mobile counterpart of the observer gate already wired on server and Python (audit F-5.4, #1392).

Arguments

• path - Path to the database directory (will be created if needed)
• observer - A Kotlin/Swift implementation of MobileObserver

Errors

Returns an error if the path is invalid or cannot be accessed.

pub fn open_with_config( path: String, config_path: String, ) -> Result<Arc<Self>, VelesError>

Opens or creates a database configured from a TOML file on disk.

The file is parsed with VelesConfig::load_from_path_engine_only: only the engine sections ([search]/[hnsw]/[storage]/[limits]/ [quantization]/[wal_batch]) are considered, any other top-level table is dropped, and VELESDB_* environment variables still layer on top of the filtered file. The database is then opened with Database::open_with_config, so every subsystem honours the loaded values instead of core defaults.

This is the mobile counterpart of the server/CLI --config wiring (issue #1549). If the app ships its config as an in-memory string (bundled asset, remote config), use open_with_config_toml instead.

Arguments

• path - Path to the database directory (will be created if needed)
• config_path - Path to an existing TOML configuration file

Errors

Fails fast — never falls back to defaults silently — if the config file is missing, unreadable, not valid TOML, or fails validation (typed as a VELES-009 configuration error), or if the database path is invalid or cannot be accessed.

pub fn open_with_config_toml( path: String, config_toml: String, ) -> Result<Arc<Self>, VelesError>

Opens or creates a database configured from an in-memory TOML string.

Same semantics as open_with_config but the TOML is passed directly (parsed with VelesConfig::from_toml_engine_only, no environment-variable layer) — the most portable option on mobile, where config often lives in a bundled asset or remote-config payload rather than a standalone file.

Arguments

• path - Path to the database directory (will be created if needed)
• config_toml - TOML configuration string (engine sections only)

Errors

Fails fast — never falls back to defaults silently — if config_toml is not valid TOML or fails validation (typed as a VELES-009 configuration error), or if the database path is invalid or cannot be accessed.

pub fn open_with_observer_and_config( path: String, observer: Arc<dyn MobileObserver>, config_path: String, ) -> Result<Arc<Self>, VelesError>

Opens or creates a database with both a read-path MobileObserver and a TOML configuration file.

Combines open_with_observer (read gate) and open_with_config (engine config) on a single handle via Database::open_with_observer_and_config.

Arguments

• path - Path to the database directory (will be created if needed)
• observer - A Kotlin/Swift implementation of MobileObserver
• config_path - Path to an existing TOML configuration file

Errors

Same fail-fast semantics as open_with_config.

pub fn open_with_observer_and_config_toml( path: String, observer: Arc<dyn MobileObserver>, config_toml: String, ) -> Result<Arc<Self>, VelesError>

Opens or creates a database with both a read-path MobileObserver and an in-memory TOML configuration string.

Combines open_with_observer (read gate) and open_with_config_toml (engine config) on a single handle.

Arguments

• path - Path to the database directory (will be created if needed)
• observer - A Kotlin/Swift implementation of MobileObserver
• config_toml - TOML configuration string (engine sections only)

Errors

Same fail-fast semantics as open_with_config_toml.

pub fn update_guardrails(&self, limits: MobileQueryLimits)

Updates query guardrail limits for every collection in this database.

This is a full replacement: all fields of limits are applied.

pub fn create_collection( &self, name: String, dimension: u32, metric: DistanceMetric, ) -> Result<(), VelesError>

Creates a new collection with the specified parameters.

Arguments

• name - Unique name for the collection
• dimension - Vector dimension (e.g., 384, 768, 1536)
• metric - Distance metric for similarity calculations

pub fn create_collection_with_storage( &self, name: String, dimension: u32, metric: DistanceMetric, storage_mode: StorageMode, ) -> Result<(), VelesError>

Creates a new collection with custom storage mode for IoT/Edge devices.

Arguments

• name - Unique name for the collection
• dimension - Vector dimension
• metric - Distance metric
• storage_mode - Storage optimization (see StorageMode)

Storage Modes

• Full: Best recall, 4 bytes/dimension
• Sq8: 4x compression, ~1% recall loss (recommended for mobile)
• Binary: 32x compression, ~5-10% recall loss (for extreme constraints)
• ProductQuantization: 8x-16x compression via trained codebooks (requires a training step before upserts)
• Rabitq: 32x compression with ~1-2% recall loss (1-bit with rotation + scalar correction)

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

Creates a metadata-only collection (no vectors).

Useful for storing reference data, lookups, or auxiliary information that doesn’t require vector similarity search.

Arguments

• name - Unique name for the collection

pub fn create_graph_collection(&self, name: String) -> Result<(), VelesError>

Creates a graph collection for knowledge graph workloads.

Creates a schemaless graph collection (no node embeddings). For graph collections with node embeddings, use create_graph_collection_with_embeddings.

Arguments

• name - Unique name for the collection

pub fn create_graph_collection_with_embeddings( &self, name: String, dimension: u32, metric: DistanceMetric, ) -> Result<(), VelesError>

Creates a graph collection with node embeddings.

Nodes in this collection can store vector embeddings and support similarity search alongside graph traversal.

Arguments

• name - Unique name for the collection
• dimension - Vector dimension for node embeddings
• metric - Distance metric for similarity calculations

pub fn get_collection( &self, name: String, ) -> Result<Option<Arc<VelesCollection>>, VelesError>

Gets a vector collection by name.

Returns None if the collection does not exist. Returns an error if the collection exists but is not a vector collection. Graph collections are queried through execute_query (VelesQL); metadata collections are not retrievable through this accessor.

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

Lists all collection names.

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

Deletes a collection by name.

pub fn train_pq( &self, collection_name: String, config: PqTrainConfig, ) -> Result<String, VelesError>

Trains a Product Quantizer on a collection.

PQ training is a database-level operation that requires access to the VelesQL TRAIN executor.

Arguments

• collection_name - Name of the collection to train PQ on
• config - PQ training configuration

Returns

Status message from the training process.

pub fn execute_query( &self, sql: String, params_json: Option<String>, ) -> Result<QueryResult, VelesError>

Executes an arbitrary VelesQL query and returns structured results.

This is the primary entry point for mobile apps to run the full VelesQL surface: SELECT, INSERT, UPDATE, DELETE, MATCH, DDL (CREATE/DROP/ALTER/TRUNCATE), TRAIN QUANTIZER, SHOW, DESCRIBE, EXPLAIN, ANALYZE, and FLUSH.

Arguments

• sql - VelesQL query string
• params_json - Optional JSON object with query parameters (keys are bare names; use $name syntax in SQL). Pass None or "{}" when no parameters are needed.

Returns

A QueryResult containing the result kind, rows (as JSON strings), row count, and a human-readable status message.

Example (Swift)

let result = try db.executeQuery(
    sql: "SELECT * FROM docs LIMIT 10",
    paramsJson: nil
)
for row in result.rows {
    let json = try JSONSerialization.jsonObject(with: row.dataJson.data(using: .utf8)!)
    print(json)
}

Trait Implementations

impl<UT> LiftRef<UT> for VelesDatabase

type LiftType = Arc<VelesDatabase>

impl<UT> LowerError<UT> for VelesDatabase

fn lower_error(obj: Self) -> RustBuffer

Lower this value for scaffolding function return

impl<UT> LowerReturn<UT> for VelesDatabase

type ReturnType = <Arc<VelesDatabase> as LowerReturn<UniFfiTag>>::ReturnType

The type that should be returned by scaffolding functions for this type.

fn lower_return(obj: Self) -> Result<Self::ReturnType, RustCallError>

Lower the return value from an scaffolding call

fn handle_failed_lift( error: LiftArgsError, ) -> Result<Self::ReturnType, RustCallError>

Lower the return value for failed argument lifts

impl<UT> TypeId<UT> for VelesDatabase

const TYPE_ID_META: MetadataBuffer