Struct EdgeStore 

pub struct EdgeStore { /* private fields */ }

Storage for graph edges with bidirectional indexing.

Provides O(1) access to edges by ID and O(degree) access to outgoing/incoming edges for any node.

Index Structure (EPIC-019 US-003)

• by_label: Secondary index for O(k) label-based queries
• outgoing_by_label: Composite index (source, label) for O(k) filtered traversal

CSR Snapshot (G1)

After loading from disk or after explicit build_read_snapshot(), the csr_snapshot field provides zero-copy &[u64] access to neighbor target IDs and edge IDs. Writes invalidate the snapshot automatically.

Implementations

impl EdgeStore

pub fn new() -> Self

Creates a new empty edge store.

pub fn with_capacity(expected_edges: usize, expected_nodes: usize) -> Self

Creates an edge store with pre-allocated capacity for better performance.

Pre-allocating reduces memory reallocation overhead when inserting many edges. With 10M edges, this can reduce peak memory usage by ~2x and improve insert throughput.

Note: when accessed through the sharded ConcurrentEdgeStore, an edge whose endpoints hash to different shards is stored in both shards (outgoing + incoming halves), which offsets part of that saving — with many shards this applies to nearly all edges.

Arguments

• expected_edges - Expected number of edges to store
• expected_nodes - Expected number of unique nodes (sources + targets)

Example

// For a graph with ~1M edges and ~100K nodes
let store = EdgeStore::with_capacity(1_000_000, 100_000);

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

Adds an edge to the store.

Creates bidirectional index entries for efficient traversal. Also maintains label-based secondary indices (EPIC-019 US-003).

Errors

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

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

Adds an edge with only the outgoing index (for cross-shard storage).

Used by ConcurrentEdgeStore when source and target are in different shards. The edge is stored and indexed by source node only.

Errors

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

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

Adds an edge with only the incoming index (for cross-shard storage).

Used by ConcurrentEdgeStore when source and target are in different shards. The edge is stored and indexed by target node only. Note: Label indices are maintained by the source shard in ConcurrentEdgeStore.

Errors

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

pub fn edge_count(&self) -> usize

Returns the total number of edges in the store.

pub fn outgoing_edge_count(&self) -> usize

Returns the count of edges where this shard is the source (for accurate cross-shard counting).

pub fn get_edge(&self, id: u64) -> Option<&GraphEdge>

Gets an edge by its ID.

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

Gets all outgoing edges from a node.

pub fn for_each_outgoing<F: FnMut(&GraphEdge)>(&self, node_id: u64, f: F)

Invokes f for each outgoing edge from node_id without allocating a Vec.

Prefer this over get_outgoing in hot loops (e.g. BFS frontiers) where the caller processes edges inline rather than collecting them.

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

Returns the number of outgoing edges from node_id without materializing them.

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

Returns the number of incoming edges to node_id without materializing them.

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

Gets all incoming edges to a node.

pub fn get_outgoing_by_label( &self, node_id: u64, label: &str, ) -> Vec<&GraphEdge>

Gets outgoing edges filtered by label using composite index - O(k) where k = result count.

Uses the outgoing_by_label composite index for fast lookup instead of iterating through all outgoing edges (EPIC-019 US-003).

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

Gets all edges with a specific label - O(k) where k = result count.

Uses the by_label secondary index for fast lookup (EPIC-019 US-003).

pub fn get_incoming_by_label( &self, node_id: u64, label: &str, ) -> Vec<&GraphEdge>

Gets incoming edges filtered by label.

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

Checks if an edge with the given ID exists.

pub fn len(&self) -> usize

Returns the number of edges in the store.

pub fn is_empty(&self) -> bool

Returns true if the store contains no edges.

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

Returns all edges in the store.

impl EdgeStore

pub fn build_read_snapshot(&mut self)

Builds a CSR snapshot from the current outgoing index.

This pre-computes contiguous arrays of target IDs, edge IDs, and interned labels for all source nodes. After calling this, BFS traversal uses with_neighbors() for zero-copy &[u64] access instead of cloning full GraphEdge objects.

When to call

• After loading from disk (graph is ready for reads)
• After a batch of mutations, before a read-heavy phase

The snapshot is automatically invalidated by any write operation.

pub fn csr_snapshot(&self) -> Option<&CsrSnapshot>

Returns a reference to the CSR snapshot, if built.

pub fn has_csr_snapshot(&self) -> bool

Returns true if a CSR snapshot is available for zero-copy reads.

pub fn with_neighbors<F, R>(&self, source_id: u64, f: F) -> R

where F: FnOnce(&[u64]) -> R,

Provides zero-copy access to neighbor target IDs via a callback.

pub fn with_neighbor_edges<F, R>(&self, source_id: u64, f: F) -> R

where F: FnOnce(&[u64], &[u64]) -> R,

Provides zero-copy access to (target_id, edge_id) pairs via callback.

impl EdgeStore

pub fn to_bytes(&self) -> Result<Vec<u8>, Error>

Serializes the edge store to bytes using postcard.

Errors

Returns an error if serialization fails.

pub fn from_bytes(bytes: &[u8]) -> Result<Self, Error>

Deserializes an edge store from bytes.

Errors

Returns an error if deserialization fails (e.g., corrupted data).

pub fn save_to_file(&self, path: &Path) -> Result<()>

Saves the edge store to a file.

Errors

Returns an error if serialization or file I/O fails.

pub fn load_from_file(path: &Path) -> Result<Self>

Loads an edge store from a file.

Automatically builds a CSR snapshot after loading for zero-copy BFS traversal (G1).

Errors

Returns an error if file I/O or deserialization fails.

impl EdgeStore

pub fn remove_edge(&mut self, edge_id: u64)

Removes an edge by ID.

Cleans up all indices: outgoing, incoming, by_label, and outgoing_by_label.

pub fn remove_edge_outgoing_only(&mut self, edge_id: u64)

Removes an edge by ID, only cleaning the outgoing index.

Used by ConcurrentEdgeStore for cross-shard cleanup. Also cleans up label indices since they are maintained by source shard.

pub fn remove_edge_incoming_only(&mut self, edge_id: u64)

Removes an edge by ID, only cleaning the incoming index.

Used by ConcurrentEdgeStore for cross-shard cleanup.

pub fn remove_node_edges(&mut self, node_id: u64)

Removes all edges connected to a node (cascade delete).

Removes both outgoing and incoming edges, cleaning up all indices including label indices (EPIC-019 US-003).

Trait Implementations

impl AdjacencySource for EdgeStore

fn neighbors(&self, node_id: u64) -> Vec<u64>

Returns outgoing neighbor target IDs from the edge index.

impl Debug for EdgeStore

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for EdgeStore

fn default() -> EdgeStore

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for EdgeStore

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for EdgeStore

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.