Struct Collection 

pub struct Collection { /* private fields */ }

A collection of vectors with associated metadata.

Implementations

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.

pub fn config(&self) -> CollectionConfig

Returns the collection configuration.

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 flush(&self) -> Result<()>

Saves the collection configuration and index to disk.

Errors

Returns an error if storage operations fail.

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_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 execute_query( &self, query: &Query, params: &HashMap<String, Value>, ) -> Result<Vec<SearchResult>>

Executes a VelesQL query on this collection.

This method unifies vector search, text search, and metadata filtering into a single interface.

Arguments

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

Errors

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

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 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 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.

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_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.

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)

Example

use velesdb_core::fusion::FusionStrategy;

// Search with 4 query reformulations using weighted fusion
let results = collection.multi_query_search(
    &[&query1, &query2, &query3, &query4],
    10,
    FusionStrategy::Weighted {
        avg_weight: 0.6,
        max_weight: 0.3,
        hit_weight: 0.1,
    },
    None,
)?;

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.

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.