Struct VectorCollection 

pub struct VectorCollection { /* private fields */ }

A vector collection combining HNSW search, payload storage, and full-text search.

VectorCollection is a typed newtype over Collection that provides a stable public API for vector workloads. All storage operations delegate to the single inner: Collection instance — no dual-storage desync.

Examples

use velesdb_core::{VectorCollection, DistanceMetric, Point, StorageMode};
use serde_json::json;

let coll = VectorCollection::create(
    "./data/docs".into(),
    "docs",
    768,
    DistanceMetric::Cosine,
    StorageMode::Full,
)?;

coll.upsert(vec![
    Point::new(1, vec![0.1; 768], Some(json!({"title": "Hello"}))),
])?;

let results = coll.search(&vec![0.1; 768], 10)?;

Implementations

impl VectorCollection

pub fn create( path: PathBuf, _name: &str, dimension: usize, metric: DistanceMetric, storage_mode: StorageMode, ) -> Result<Self>

Creates a new VectorCollection at the given path.

Errors

Returns an error if the directory cannot be created or storage fails.

pub fn open(path: PathBuf) -> Result<Self>

Opens an existing VectorCollection from disk.

Errors

Returns an error if the config file cannot be read or storage cannot be opened.

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

Flushes all engines to disk and saves the config.

Errors

Returns an error if any flush operation fails.

pub fn name(&self) -> String

Returns the collection name.

pub fn dimension(&self) -> usize

Returns the vector dimension.

pub fn metric(&self) -> DistanceMetric

Returns the distance metric.

pub fn storage_mode(&self) -> StorageMode

Returns the storage mode.

pub fn len(&self) -> usize

Returns the number of points in the collection.

pub fn is_empty(&self) -> bool

Returns true if the collection is empty.

pub fn all_ids(&self) -> Vec<u64>

Returns all point IDs.

pub fn config(&self) -> CollectionConfig

Returns the current collection config.

pub fn upsert_bulk(&self, points: &[Point]) -> Result<usize>

Bulk insert optimized for high-throughput import.

Errors

Returns an error if any point has a mismatched dimension.

pub fn upsert(&self, points: impl IntoIterator<Item = Point>) -> Result<()>

Inserts or updates points.

Errors

Returns an error if the dimension mismatches or storage fails.

pub fn get(&self, ids: &[u64]) -> Vec<Option<Point>>

Retrieves points by IDs.

pub fn delete(&self, ids: &[u64]) -> Result<()>

Deletes points by IDs.

Errors

Returns an error if storage operations fail.

pub fn search(&self, query: &[f32], k: usize) -> Result<Vec<SearchResult>>

Performs kNN vector search.

Errors

pub fn text_search(&self, query: &str, k: usize) -> Vec<SearchResult>

Performs full-text BM25 search.

pub fn search_with_ef( &self, query: &[f32], k: usize, ef_search: usize, ) -> Result<Vec<SearchResult>>

kNN search with explicit ef_search override.

Errors

pub fn search_with_filter( &self, query: &[f32], k: usize, filter: &Filter, ) -> Result<Vec<SearchResult>>

kNN search with metadata filter.

Errors

pub fn search_ids(&self, query: &[f32], k: usize) -> Result<Vec<(u64, f32)>>

Returns (id, score) pairs without payload hydration.

Errors

pub fn text_search_with_filter( &self, query: &str, k: usize, filter: &Filter, ) -> Vec<SearchResult>

Full-text search with metadata filter.

pub fn hybrid_search( &self, vector: &[f32], text: &str, k: usize, alpha: Option<f32>, ) -> Result<Vec<SearchResult>>

Hybrid search (vector + BM25 with RRF fusion).

Errors

pub fn hybrid_search_with_filter( &self, vector: &[f32], text: &str, k: usize, alpha: Option<f32>, filter: &Filter, ) -> Result<Vec<SearchResult>>

Hybrid search with metadata filter.

Errors

pub fn search_batch_with_filters( &self, queries: &[&[f32]], k: usize, filters: &[Option<Filter>], ) -> Result<Vec<Vec<SearchResult>>>

Batch search with per-query filters.

Errors

pub fn multi_query_search( &self, queries: &[&[f32]], k: usize, strategy: FusionStrategy, filter: Option<&Filter>, ) -> Result<Vec<SearchResult>>

Multi-query search (multiple vectors fused).

Errors

pub fn multi_query_search_ids( &self, queries: &[&[f32]], k: usize, strategy: FusionStrategy, ) -> Result<Vec<(u64, f32)>>

Multi-query search returning only IDs and fused scores.

Errors

pub fn upsert_metadata( &self, points: impl IntoIterator<Item = Point>, ) -> Result<()>

Inserts or updates metadata-only points (no vectors).

Errors

pub fn create_index(&self, field: &str) -> Result<()>

Creates a secondary metadata index on a payload field.

Errors

pub fn has_secondary_index(&self, field: &str) -> bool

Returns true if a secondary index exists on field.

pub fn create_property_index(&self, label: &str, property: &str) -> Result<()>

Creates a property index for O(1) equality lookups.

Errors

pub fn create_range_index(&self, label: &str, property: &str) -> Result<()>

Creates a range index for O(log n) range queries.

Errors

pub fn has_property_index(&self, label: &str, property: &str) -> bool

Returns true if a property index exists.

pub fn has_range_index(&self, label: &str, property: &str) -> bool

Returns true if a range index exists.

pub fn list_indexes(&self) -> Vec<IndexInfo>

Lists all index definitions on this collection.

pub fn drop_index(&self, label: &str, property: &str) -> Result<bool>

Drops an index. Returns true if an index was removed.

Errors

pub fn indexes_memory_usage(&self) -> usize

Returns total memory usage of all indexes in bytes.

pub fn execute_match( &self, match_clause: &MatchClause, params: &HashMap<String, Value>, ) -> Result<Vec<MatchResult>>

Executes a graph MATCH query.

Errors

pub fn execute_match_with_similarity( &self, match_clause: &MatchClause, query_vector: &[f32], threshold: f32, params: &HashMap<String, Value>, ) -> Result<Vec<MatchResult>>

Executes a MATCH query with vector similarity filtering.

Errors

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

Executes an aggregation query (GROUP BY / COUNT / SUM / AVG / MIN / MAX).

Errors

pub fn get_stats(&self) -> CollectionStats

Returns CBO statistics.

pub fn is_metadata_only(&self) -> bool

Returns true if the collection is a metadata-only collection.

pub fn analyze(&self) -> Result<CollectionStats>

Analyzes the collection and returns fresh statistics.

Errors

pub fn sparse_search( &self, query: &SparseVector, k: usize, index_name: &str, ) -> Result<Vec<SearchResult>>

Performs sparse-only search on the named index.

Errors

Returns an error if the named sparse index does not exist.

pub fn hybrid_sparse_search( &self, dense_vector: &[f32], sparse_query: &SparseVector, k: usize, index_name: &str, strategy: &FusionStrategy, ) -> Result<Vec<SearchResult>>

Performs hybrid dense+sparse search with RRF fusion.

Errors

Returns an error if dense or sparse search fails, or fusion errors.

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

Executes a VelesQL query.

Errors

pub fn stream_insert(&self, point: Point) -> Result<(), BackpressureError>

Sends a point into the streaming ingestion channel.

Returns Ok(()) on success (202 semantics). Returns BackpressureError::BufferFull when the channel is at capacity, or BackpressureError::NotConfigured if streaming is not active.

Errors

Returns BackpressureError on buffer-full or not-configured.

pub fn push_to_delta_if_active(&self, entries: &[(u64, Vec<f32>)])

Pushes (id, vector) entries into the delta buffer if it is active.

No-op when the delta buffer is inactive. This is the public interface used by streaming upsert handlers (e.g., NDJSON stream endpoint) to keep the delta buffer in sync after a successful upsert_bulk call.

pub fn is_delta_active(&self) -> bool

Returns true if the delta buffer is currently active (HNSW rebuild in progress). External callers can use this to decide whether to snapshot entries for delta before a upsert_bulk call.

pub fn execute_query_str( &self, sql: &str, params: &HashMap<String, Value>, ) -> Result<Vec<SearchResult>>

Executes a raw VelesQL string.

Errors

Trait Implementations

impl Clone for VectorCollection

fn clone(&self) -> VectorCollection

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.