Struct Collection 

pub struct Collection { /* private fields */ }

A collection of vectors with associated metadata.

Implementations

impl Collection

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

Inserts or updates points in the collection.

Accepts any iterator of points (Vec, slice, array, etc.)

Errors

Returns an error if any point has a mismatched dimension, or if attempting to insert vectors into a metadata-only collection.

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

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

This method is for metadata-only collections. Points should have empty vectors and only contain payload data.

Errors

Returns an error if storage operations fail.

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

Bulk insert optimized for high-throughput import.

Performance

This method is optimized for bulk loading:

• Uses parallel HNSW insertion (rayon)
• Single flush at the end (not per-point)
• No HNSW index save (deferred for performance)
• ~15x faster than previous sequential approach on large batches (5000+)
• Benchmark: 25-30 Kvec/s on 768D vectors

Errors

Returns an error if any point has a mismatched dimension.

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

Retrieves points by their IDs.

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

Deletes points by their IDs.

Errors

Returns an error if storage operations fail.

pub fn len(&self) -> usize

Returns the number of points in the collection. Perf: Uses cached point_count from config instead of acquiring storage lock

pub fn is_empty(&self) -> bool

Returns true if the collection is empty. Perf: Uses cached point_count from config instead of acquiring storage lock

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

Returns all point IDs in the collection.

impl Collection

pub fn add_edge(&self, edge: GraphEdge) -> Result<()>

Adds an edge to the collection’s knowledge graph.

Arguments

• edge - The edge to add (id, source, target, label, properties)

Errors

Returns Error::EdgeExists if an edge with the same ID already exists.

Example

use velesdb_core::collection::graph::GraphEdge;

let edge = GraphEdge::new(1, 100, 200, "KNOWS")?;
collection.add_edge(edge)?;

pub fn get_all_edges(&self) -> Vec<GraphEdge>

Gets all edges from the collection’s knowledge graph.

Note: This iterates through all stored edges. For large graphs, consider using get_edges_by_label or get_outgoing_edges for more targeted queries.

Returns

Vector of all edges in the graph (cloned).

pub fn get_edges_by_label(&self, label: &str) -> Vec<GraphEdge>

Gets edges filtered by label.

Arguments

• label - The edge label (relationship type) to filter by

Returns

Vector of edges with the specified label (cloned).

pub fn get_outgoing_edges(&self, node_id: u64) -> Vec<GraphEdge>

Gets outgoing edges from a specific node.

Arguments

• node_id - The source node ID

Returns

Vector of edges originating from the specified node (cloned).

pub fn get_incoming_edges(&self, node_id: u64) -> Vec<GraphEdge>

Gets incoming edges to a specific node.

Arguments

• node_id - The target node ID

Returns

Vector of edges pointing to the specified node (cloned).

pub fn traverse_bfs( &self, source: u64, max_depth: u32, rel_types: Option<&[&str]>, limit: usize, ) -> Result<Vec<TraversalResult>>

Traverses the graph using BFS from a source node.

Arguments

• source - Starting node ID
• max_depth - Maximum traversal depth
• rel_types - Optional filter by relationship types
• limit - Maximum number of results

Returns

Vector of traversal results with target nodes and paths.

Errors

Returns an error if traversal fails.

pub fn traverse_dfs( &self, source: u64, max_depth: u32, rel_types: Option<&[&str]>, limit: usize, ) -> Result<Vec<TraversalResult>>

Traverses the graph using DFS from a source node.

Arguments

• source - Starting node ID
• max_depth - Maximum traversal depth
• rel_types - Optional filter by relationship types
• limit - Maximum number of results

Returns

Vector of traversal results with target nodes and paths.

Errors

Returns an error if traversal fails.

pub fn get_node_degree(&self, node_id: u64) -> (usize, usize)

Gets the in-degree and out-degree of a node.

Arguments

• node_id - The node ID

Returns

Tuple of (in_degree, out_degree).

pub fn remove_edge(&self, edge_id: u64) -> bool

Removes an edge from the graph by ID.

Arguments

• edge_id - The edge ID to remove

Returns

true if the edge existed and was removed, false if it didn’t exist.

pub fn edge_count(&self) -> usize

Returns the total number of edges in the graph.

pub fn graph_schema(&self) -> Option<GraphSchema>

Returns the graph schema stored in the collection config, if any.

pub fn is_graph(&self) -> bool

Returns true if this collection was created as a graph collection.

pub fn has_embeddings(&self) -> bool

Returns true if this graph collection stores node embeddings.

pub fn store_node_payload(&self, node_id: u64, payload: &Value) -> Result<()>

Stores a JSON payload for a graph node.

Errors

Returns an error if storage fails.

pub fn get_node_payload(&self, node_id: u64) -> Result<Option<Value>>

Retrieves the JSON payload for a graph node.

Errors

Returns an error if retrieval fails.

pub fn traverse_bfs_config( &self, source_id: u64, config: &TraversalConfig, ) -> Vec<TraversalResult>

BFS traversal using the core bfs_stream iterator.

pub fn traverse_dfs_config( &self, source_id: u64, config: &TraversalConfig, ) -> Vec<TraversalResult>

DFS traversal (iterative) using TraversalConfig.

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

Searches for similar graph nodes by embedding vector.

Only available if has_embeddings() returns true.

Errors

Returns Error::VectorNotAllowed if no embeddings are configured, or Error::DimensionMismatch if the query dimension is wrong.

impl Collection

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

Creates a secondary metadata index for a payload field.

Errors

Returns Ok(()) on success. Index creation is idempotent.

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

Checks whether a secondary metadata index exists for a field.

pub fn secondary_index_lookup( &self, field_name: &str, value: &JsonValue, ) -> Option<Vec<u64>>

Looks up matching point IDs for an indexed field value.

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

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

Arguments

• label - Node label to index (e.g., “Person”)
• property - Property name to index (e.g., “email”)

Errors

Returns Ok(()) on success. Index creation is idempotent.

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

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

Arguments

• label - Node label to index (e.g., “Event”)
• property - Property name to index (e.g., “timestamp”)

Errors

Returns Ok(()) on success. Index creation is idempotent.

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

Check if a property index exists.

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

Check if a range index exists.

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

List all indexes on this collection.

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

Drop an index (either property or range).

Arguments

• label - Node label
• property - Property name

Returns

Ok(true) if an index was dropped, Ok(false) if no index existed.

Errors

Returns an error if underlying index stores fail while dropping.

pub fn indexes_memory_usage(&self) -> usize

Get total memory usage of all indexes.

impl Collection

pub fn create( path: PathBuf, dimension: usize, metric: DistanceMetric, ) -> Result<Self>

Creates a new collection at the specified path.

Errors

Returns an error if the directory cannot be created or the config cannot be saved.

pub fn create_with_options( path: PathBuf, dimension: usize, metric: DistanceMetric, storage_mode: StorageMode, ) -> Result<Self>

Creates a new collection with custom storage options.

Arguments

• path - Path to the collection directory
• dimension - Vector dimension
• metric - Distance metric
• storage_mode - Vector storage mode (Full, SQ8, Binary)

Errors

Returns an error if the directory cannot be created or the config cannot be saved.

pub fn create_typed( path: PathBuf, name: &str, collection_type: &CollectionType, ) -> Result<Self>

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

Arguments

• path - Path to the collection directory
• name - Name of the collection
• collection_type - Type of collection to create

Errors

Returns an error if the directory cannot be created or the config cannot be saved.

pub fn create_metadata_only(path: PathBuf, name: &str) -> Result<Self>

Creates a new metadata-only collection (no vectors, no HNSW index).

Metadata-only collections are optimized for storing reference data, catalogs, and other non-vector data. They support CRUD operations and VelesQL queries on payload, but NOT vector search.

Errors

Returns an error if the directory cannot be created or the config cannot be saved.

pub fn is_metadata_only(&self) -> bool

Returns true if this is a metadata-only collection.

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

Opens an existing collection from the specified path.

Errors

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

INVARIANT(CACHE-01): write_generation starts at 0 on open

Every call to Collection::open initialises write_generation to 0. This is safe for cache correctness because:

1. The plan cache is not persisted across process restarts — it is always empty when the database opens. There are therefore no stale cached plans that could be incorrectly served.

2. Database::load_collections bumps schema_version after loading at least one collection (C-3). Any plan key built before the load would carry the pre-load schema_version and would miss the cache even if the write_generation happened to match.

3. Within a single process lifetime the write_generation is only ever incremented (never reset), so a cache key built with generation N will never be reused once the generation advances past N.

pub fn create_graph_collection( path: PathBuf, name: &str, schema: GraphSchema, embedding_dim: Option<usize>, metric: DistanceMetric, ) -> Result<Self>

Creates a new graph collection (with optional node embeddings).

Persists graph_schema and embedding_dimension in config.json.

Errors

Returns an error if the directory cannot be created or the config cannot be saved.

pub fn config(&self) -> CollectionConfig

Returns the collection configuration.

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

Saves the collection configuration and index to disk.

Errors

Returns an error if storage operations fail.

impl Collection

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

Analyzes the collection and returns statistics.

This method collects:

• Row count and deleted count
• Index statistics (HNSW entry count)

Example

let stats = collection.analyze()?;
println!("Row count: {}", stats.row_count);
println!("Deletion ratio: {:.1}%", stats.deletion_ratio() * 100.0);

Errors

Returns an error if statistics cannot be collected.

Panics

Panics if point_count exceeds u64::MAX (extremely unlikely on 64-bit systems).

pub fn get_stats(&self) -> CollectionStats

Returns cached statistics if available and fresh, otherwise recomputes.

Results are cached for 30 seconds (STATS_TTL) to avoid re-scanning payload storage on every execute_query() call. Mutating methods (upsert, delete, etc.) invalidate the cache so the next call always recomputes.

Note

Returns default stats on error (intentional for convenience). Use analyze() directly if error handling is required.

pub fn estimate_column_selectivity(&self, column: &str) -> f64

Returns the selectivity estimate for a column.

Selectivity is 1/cardinality, representing the probability that a random row matches a specific value.

impl Collection

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

Performs batch search for multiple query vectors in parallel with metadata filtering. Supports a different filter for each query in the batch.

Arguments

• queries - List of query vector slices
• k - Maximum number of results per query
• filters - List of optional filters (must match queries length)

Returns

Vector of search results for each query, matching its respective filter.

Errors

Returns an error if queries and filters have different lengths or dimension mismatch.

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

Performs batch search for multiple query vectors in parallel with a single metadata filter.

Arguments

• queries - List of query vector slices
• k - Maximum number of results per query
• filter - Metadata filter to apply to all results

Errors

Returns an error if any query has incorrect dimension.

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

Performs batch search for multiple query vectors in parallel.

This method is optimized for high throughput using parallel index traversal.

Arguments

• queries - List of query vector slices
• k - Maximum number of results per query

Returns

Vector of search results for each query, with full point data.

Errors

Returns an error if any query vector dimension doesn’t match the collection.

pub fn multi_query_search( &self, vectors: &[&[f32]], top_k: usize, fusion: FusionStrategy, filter: Option<&Filter>, ) -> Result<Vec<SearchResult>>

Performs multi-query search with result fusion.

This method executes parallel searches for multiple query vectors and fuses the results using the specified fusion strategy. Ideal for Multiple Query Generation (MQG) pipelines where multiple reformulations of a user query are searched simultaneously.

Arguments

• vectors - Slice of query vectors (all must have same dimension)
• top_k - Maximum number of results to return after fusion
• fusion - Strategy for combining results (Average, Maximum, RRF, Weighted)
• filter - Optional metadata filter to apply to all queries

Returns

Vector of SearchResult sorted by fused score descending.

Errors

Returns an error if:

• vectors is empty
• Any vector has incorrect dimension
• More than 10 vectors are provided (configurable limit)

pub fn multi_query_search_ids( &self, vectors: &[&[f32]], top_k: usize, fusion: FusionStrategy, ) -> Result<Vec<(u64, f32)>>

Performs multi-query search returning only IDs and fused scores.

This is a faster variant of multi_query_search that skips fetching vector and payload data. Use when you only need document IDs.

Arguments

• vectors - Slice of query vectors
• top_k - Maximum number of results
• fusion - Fusion strategy

Returns

Vector of (id, fused_score) tuples sorted by score descending.

Errors

Returns an error if vectors is empty, exceeds max limit, or has dimension mismatch.

impl Collection

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

Execute an aggregation query and return results as JSON.

Supports COUNT(*), COUNT(column), SUM, AVG, MIN, MAX. Uses streaming aggregation - O(1) memory, single pass over data.

Arguments

• query - Parsed VelesQL query with aggregation functions
• params - Query parameters for placeholders

Returns

JSON object with aggregation results, e.g.:

{"count": 100, "sum_price": 5000.0, "avg_rating": 4.5}

Errors

Returns an error when SELECT does not contain aggregations, when HAVING is used without GROUP BY, or when underlying scan/filter/aggregation operations fail.

impl Collection

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

Executes a MATCH query with similarity scoring (EPIC-045 US-003).

This method combines graph pattern matching with vector similarity, enabling hybrid queries like: MATCH (n:Article)-[:CITED]->(m) WHERE similarity(m.embedding, $query) > 0.8 RETURN m

Arguments

• match_clause - The parsed MATCH clause
• query_vector - The query vector for similarity scoring
• similarity_threshold - Minimum similarity score (0.0 to 1.0)
• params - Query parameters

Returns

Vector of MatchResult with similarity scores and projected properties.

Errors

Returns an error on dimension mismatch, underlying storage/search errors, or ORDER BY failures.

pub fn order_match_results( &self, results: &mut [MatchResult], order_by: &str, descending: bool, )

Applies ORDER BY to match results (EPIC-045 US-005).

Supports ordering by:

• similarity() - Vector similarity score
• Property path (e.g., n.name)
• Depth

pub fn match_results_to_search_results( &self, match_results: Vec<MatchResult>, ) -> Result<Vec<SearchResult>>

Converts MatchResults to SearchResults for unified API (EPIC-045 US-002).

This allows MATCH queries to return the same result type as SELECT queries, enabling consistent downstream processing.

Errors

Returns an error when vector storage access fails for any matched node.

impl Collection

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

Executes a MATCH query on this collection (EPIC-045 US-002).

This method performs graph pattern matching by:

1. Finding start nodes matching the first node pattern
2. Traversing relationships according to the pattern
3. Filtering results by WHERE clause conditions
4. Returning results according to RETURN clause

Arguments

• match_clause - The parsed MATCH clause
• params - Query parameters for resolving placeholders

Returns

Vector of MatchResult containing matched nodes and their bindings.

Errors

Returns an error if the query cannot be executed. Executes a MATCH query without guard-rail context (backward-compatible entry point).

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

Executes a MATCH query on this collection (EPIC-045 US-002, EPIC-048).

This method performs graph pattern matching by:

1. Finding start nodes matching the first node pattern
2. Traversing relationships according to the pattern
3. Enforcing guard-rail limits (depth, cardinality, timeout) if a context is provided
4. Filtering results by WHERE clause conditions
5. Returning results according to RETURN clause

Arguments

• match_clause - The parsed MATCH clause
• params - Query parameters for resolving placeholders
• ctx - Optional guard-rail context for enforcing limits

Errors

Returns an error if the query cannot be executed or a guard-rail is violated.

impl Collection

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

Executes a VelesQL query on this collection with the "default" client id.

This method unifies vector search, text search, and metadata filtering into a single interface. For per-client rate limiting use execute_query_with_client.

Errors

Returns an error if the query cannot be executed (e.g., missing parameters).

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

Executes a VelesQL query with a specific client identifier for per-client rate limiting.

Each distinct client_id maintains an independent token bucket, so one busy client cannot exhaust the quota of another.

Errors

Returns an error if the query cannot be executed or a guard-rail fires.

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

Parses and executes a VelesQL query string, using the collection-level parse cache (P1-A).

Equivalent to calling Parser::parse(sql) followed by execute_query(), but caches parsed ASTs so repeated identical queries avoid re-parsing overhead.

Arguments

• sql - Raw VelesQL query string
• params - Query parameters for resolving placeholders (e.g., $v)

Errors

Returns a parse error if sql is invalid, or an execution error if the query fails.

impl Collection

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

Sparse-only search on the default sparse index.

Errors

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

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

Sparse-only search on a named sparse 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, strategy: &FusionStrategy, ) -> Result<Vec<SearchResult>>

Hybrid dense+sparse search with RRF fusion on the default sparse index.

Runs both dense (HNSW) and sparse branches, then fuses using the provided strategy (typically RRF with k=60).

Errors

Returns an error if the sparse index does not exist or fusion fails.

impl Collection

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

Performs full-text search using BM25.

Arguments

• query - Text query to search for
• k - Maximum number of results to return

Returns

Vector of search results sorted by BM25 score (descending).

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

Performs full-text search with metadata filtering.

Arguments

• query - Text query to search for
• k - Maximum number of results to return
• filter - Metadata filter to apply

Returns

Vector of search results sorted by BM25 score (descending).

pub fn hybrid_search( &self, vector_query: &[f32], text_query: &str, k: usize, vector_weight: Option<f32>, ) -> Result<Vec<SearchResult>>

Performs hybrid search combining vector similarity and full-text search.

Uses Reciprocal Rank Fusion (RRF) to combine results from both searches.

Arguments

• vector_query - Query vector for similarity search
• text_query - Text query for BM25 search
• k - Maximum number of results to return
• vector_weight - Weight for vector results (0.0-1.0, default 0.5)

Performance (v0.9+)

• Streaming RRF: BinaryHeap maintains top-k during fusion (O(n log k) vs O(n log n))
• Vector-first gating: Text search limited to 2k candidates for efficiency
• FxHashMap: Faster hashing for score aggregation

Errors

Returns an error if the query vector dimension doesn’t match.

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

Performs hybrid search (vector + text) with metadata filtering.

Uses Reciprocal Rank Fusion (RRF) to combine results from both searches, then applies metadata filter.

Arguments

• vector_query - Query vector for similarity search
• text_query - Text query for BM25 search
• k - Maximum number of results to return
• vector_weight - Weight for vector results (0.0-1.0, default 0.5)
• filter - Metadata filter to apply

Errors

Returns an error if the query vector dimension doesn’t match.

impl Collection

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

Searches for the k nearest neighbors of the query vector.

Uses HNSW index for fast approximate nearest neighbor search.

Errors

Returns an error if the query vector dimension doesn’t match the collection, or if this is a metadata-only collection (use query() instead).

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

Performs vector similarity search with custom ef_search parameter.

Higher ef_search = better recall, slower search. Default ef_search is 128 (Balanced mode).

Errors

Returns an error if the query vector dimension doesn’t match the collection.

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

Performs fast vector similarity search returning only IDs and scores.

Perf: This is ~3-5x faster than search() because it skips vector/payload retrieval. Use this when you only need IDs and scores, not full point data.

Arguments

• query - Query vector
• k - Maximum number of results to return

Returns

Vector of (id, score) tuples sorted by similarity.

Errors

Returns an error if the query vector dimension doesn’t match the collection.

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

Searches for the k nearest neighbors with metadata filtering.

Performs post-filtering: retrieves more candidates from HNSW, then filters by metadata conditions.

Arguments

• query - Query vector
• k - Maximum number of results to return
• filter - Metadata filter to apply

Errors

Returns an error if the query vector dimension doesn’t match the collection.

impl Collection

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

Sends a point into the streaming ingestion channel.

Returns BackpressureError::NotConfigured if streaming is not active on this collection.

Errors

Returns BackpressureError on buffer-full or not-configured.

pub fn enable_streaming(&self, config: StreamingConfig)

Enables streaming ingestion on this collection.

Creates a StreamIngester with the given config and stores it in the stream_ingester field. Points can then be submitted via stream_insert.

Calling this when streaming is already active replaces the existing ingester (the old drain task is aborted via Drop).

Future: auto-enable from persisted StreamingConfig on open (STREAM-01)

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

Pushes entries into the delta buffer if it is currently active.

This is a convenience method for callers (e.g., the REST upsert handlers) that do not have direct access to the delta buffer internals.

No-op when the delta buffer is inactive.

Trait Implementations

impl Clone for Collection

fn clone(&self) -> Collection

Returns a duplicate of the value.

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

Performs copy-assignment from source.