Struct GraphCollection 

pub struct GraphCollection { /* private fields */ }

A graph collection storing typed relationships between nodes.

Node embeddings are optional: if dimension is None, no vector index is created.

Examples

use velesdb_core::{GraphCollection, GraphSchema, GraphEdge, DistanceMetric};

let coll = GraphCollection::create(
    "./data/kg".into(),
    "knowledge",
    None,                    // no embeddings
    DistanceMetric::Cosine,  // unused when no embeddings
    GraphSchema::schemaless(),
)?;

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

Implementations

impl GraphCollection

pub fn diagnostics(&self) -> CollectionDiagnostics

Returns diagnostic information about this collection.

impl GraphCollection

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

Creates a new GraphCollection.

Errors

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

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

Opens an existing GraphCollection from disk.

Errors

Returns an error if config or storage cannot be opened.

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

Flushes all state to disk.

Issue #423: This fast-path flush skips vectors.idx serialization. The WAL provides crash recovery for the vector index.

Errors

Returns an error if any flush operation fails.

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

Full durability flush including vectors.idx serialization.

Issue #423: Use on graceful shutdown to avoid a full WAL replay on the next startup.

Errors

Returns an error if any flush operation fails.

pub fn name(&self) -> String

Returns the collection name.

pub fn schema(&self) -> GraphSchema

Returns the graph schema stored in config.

Returns GraphSchema::schemaless() for collections that have no schema set.

pub fn has_embeddings(&self) -> bool

Returns true if this collection stores node embeddings.

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

Adds an edge between two nodes.

Errors

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

Examples

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

pub fn add_edges_batch(&self, edges: Vec<GraphEdge>) -> usize

Adds multiple edges in batch (much faster than calling add_edge in a loop).

Acquires locks once for the entire batch and rebuilds the CSR snapshot once at the end. Duplicate edge IDs are silently skipped.

Returns

Number of edges successfully added.

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

Returns edges, optionally filtered by label.

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

Returns all outgoing edges from a node.

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

Returns all incoming edges to a node.

pub fn edge_count(&self) -> usize

Returns the total number of edges in the graph without materializing them.

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

Returns (in_degree, out_degree) for a node.

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

Returns the IDs of all nodes that have a stored payload.

Nodes that appear only as edge endpoints without a stored payload are not included. Use GraphCollection::get_edges to discover all referenced node IDs.

pub fn scroll_batch( &self, cursor: Option<u64>, batch_size: usize, filter: Option<&Filter>, ) -> Result<ScrollBatch>

Returns the next batch of points for scroll iteration.

Delegates to the inner collection’s scroll_batch (parallel implementation to VectorCollection::scroll_batch).

Errors

Returns an error if batch_size is 0.

pub fn len(&self) -> usize

Returns the number of nodes (points) stored in this collection.

pub fn is_empty(&self) -> bool

Returns true if the collection contains no nodes.

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

Retrieves nodes by IDs, returning None for missing entries.

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

Deletes nodes by IDs.

Missing IDs are silently ignored.

Errors

Returns an error if storage operations fail.

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

Removes an edge from the graph by ID.

Returns true if the edge existed and was removed, false otherwise.

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

Performs BFS traversal from a source node.

Examples

let config = TraversalConfig { max_depth: 3, ..TraversalConfig::default() };
let results = coll.traverse_bfs(100, &config);
for r in &results {
    println!("node={} depth={}", r.target_id, r.depth);
}

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

Performs DFS traversal from a source node.

pub fn traverse_bfs_parallel( &self, start_nodes: &[u64], config: &TraversalConfig, ) -> Vec<TraversalResult>

Performs parallel BFS traversal from multiple start nodes.

When start_nodes exceeds the parallel threshold (100 nodes), rayon distributes independent per-start-node BFS traversals across CPU cores. Results are deduplicated by path signature and truncated to config.limit.

Examples

let config = TraversalConfig { max_depth: 3, ..TraversalConfig::default() };
let results = coll.traverse_bfs_parallel(&[100, 200, 300], &config);
for r in &results {
    println!("node={} depth={}", r.target_id, r.depth);
}

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

Inserts or updates node payload (properties).

Errors

Returns an error if storage fails.

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

👎Deprecated since 1.6.0:

Use upsert_node_payload() instead

Inserts or updates node payload (properties).

Errors

Returns an error if storage fails.

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

Retrieves node payload.

Errors

Returns an error if retrieval fails.

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

Searches for similar nodes by embedding (only available if has_embeddings()).

Errors

Returns Error::VectorNotAllowed if this collection has no embeddings, or Error::DimensionMismatch if the query dimension is wrong.

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

Alias for search_by_embedding.

Provided for API parity with crate::VectorCollection::search.

Errors

Returns Error::VectorNotAllowed if this collection has no embeddings, or Error::DimensionMismatch if the query dimension is wrong.

impl GraphCollection

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

Executes a parsed VelesQL query.

Errors

Returns an error if the query is invalid or execution fails.

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

Executes a query with instrumentation and returns plan + actual stats.

Delegates to crate::Database::explain_analyze_query.

Errors

Returns an error if the query is invalid or execution fails.

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

Executes a raw VelesQL string, parsing it before execution.

Errors

• Returns an error if the SQL string cannot be parsed.
• Returns an error if query execution fails.

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

Executes a MATCH graph pattern query.

Errors

Returns an error if the query cannot be executed.

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 vector similarity scoring.

Errors

Returns an error on dimension mismatch or execution failure.

Trait Implementations

impl Clone for GraphCollection

fn clone(&self) -> GraphCollection

Returns a duplicate of the value.

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

Performs copy-assignment from source.