grafeo_core/graph/
traits.rs

1//! Storage traits for the graph engine.
2//!
3//! These traits capture the minimal surface that query operators need from
4//! the graph store. The split is intentional:
5//!
6//! - [`GraphStore`]: Read-only operations (scans, lookups, traversal, statistics)
7//! - [`GraphStoreMut`]: Write operations (create, delete, mutate)
8//!
9//! Admin operations (index management, MVCC internals, schema introspection,
10//! statistics recomputation, WAL recovery) stay on the concrete [`LpgStore`]
11//! and are not part of these traits.
12//!
13//! ## Design rationale
14//!
15//! The traits work with typed graph objects (`Node`, `Edge`, `Value`) rather
16//! than raw bytes. This preserves zero-overhead access for in-memory storage
17//! while allowing future backends (SpilloverStore, disk-backed) to implement
18//! the same interface with transparent serialization where needed.
19//!
20//! [`LpgStore`]: crate::graph::lpg::LpgStore
21
22use crate::graph::Direction;
23use crate::graph::lpg::CompareOp;
24use crate::graph::lpg::{Edge, Node};
25use crate::statistics::Statistics;
26use arcstr::ArcStr;
27use grafeo_common::types::{EdgeId, EpochId, NodeId, PropertyKey, TransactionId, Value};
28use grafeo_common::utils::hash::FxHashMap;
29use std::sync::Arc;
30
31/// Read-only graph operations used by the query engine.
32///
33/// This trait captures the minimal surface that scan, expand, filter,
34/// project, and shortest-path operators need. Implementations may serve
35/// data from memory, disk, or a hybrid of both.
36///
37/// # Object safety
38///
39/// This trait is object-safe: you can use `Arc<dyn GraphStore>` for dynamic
40/// dispatch. Traversal methods return `Vec` instead of `impl Iterator` to
41/// enable this.
42pub trait GraphStore: Send + Sync {
43    // --- Point lookups ---
44
45    /// Returns a node by ID (latest visible version at current epoch).
46    fn get_node(&self, id: NodeId) -> Option<Node>;
47
48    /// Returns an edge by ID (latest visible version at current epoch).
49    fn get_edge(&self, id: EdgeId) -> Option<Edge>;
50
51    /// Returns a node visible to a specific transaction.
52    fn get_node_versioned(
53        &self,
54        id: NodeId,
55        epoch: EpochId,
56        transaction_id: TransactionId,
57    ) -> Option<Node>;
58
59    /// Returns an edge visible to a specific transaction.
60    fn get_edge_versioned(
61        &self,
62        id: EdgeId,
63        epoch: EpochId,
64        transaction_id: TransactionId,
65    ) -> Option<Edge>;
66
67    /// Returns a node using pure epoch-based visibility (no transaction context).
68    ///
69    /// The node is visible if `created_epoch <= epoch` and not deleted at or
70    /// before `epoch`. Used for time-travel queries where transaction ownership
71    /// must not bypass the epoch check.
72    fn get_node_at_epoch(&self, id: NodeId, epoch: EpochId) -> Option<Node>;
73
74    /// Returns an edge using pure epoch-based visibility (no transaction context).
75    fn get_edge_at_epoch(&self, id: EdgeId, epoch: EpochId) -> Option<Edge>;
76
77    // --- Property access (fast path, avoids loading full entity) ---
78
79    /// Gets a single property from a node without loading all properties.
80    fn get_node_property(&self, id: NodeId, key: &PropertyKey) -> Option<Value>;
81
82    /// Gets a single property from an edge without loading all properties.
83    fn get_edge_property(&self, id: EdgeId, key: &PropertyKey) -> Option<Value>;
84
85    /// Gets a property for multiple nodes in a single batch operation.
86    fn get_node_property_batch(&self, ids: &[NodeId], key: &PropertyKey) -> Vec<Option<Value>>;
87
88    /// Gets all properties for multiple nodes in a single batch operation.
89    fn get_nodes_properties_batch(&self, ids: &[NodeId]) -> Vec<FxHashMap<PropertyKey, Value>>;
90
91    /// Gets selected properties for multiple nodes (projection pushdown).
92    fn get_nodes_properties_selective_batch(
93        &self,
94        ids: &[NodeId],
95        keys: &[PropertyKey],
96    ) -> Vec<FxHashMap<PropertyKey, Value>>;
97
98    /// Gets selected properties for multiple edges (projection pushdown).
99    fn get_edges_properties_selective_batch(
100        &self,
101        ids: &[EdgeId],
102        keys: &[PropertyKey],
103    ) -> Vec<FxHashMap<PropertyKey, Value>>;
104
105    // --- Traversal ---
106
107    /// Returns neighbor node IDs in the specified direction.
108    ///
109    /// Returns `Vec` instead of an iterator for object safety. The underlying
110    /// `ChunkedAdjacency` already produces a `Vec` internally.
111    fn neighbors(&self, node: NodeId, direction: Direction) -> Vec<NodeId>;
112
113    /// Returns (target_node, edge_id) pairs for edges from a node.
114    fn edges_from(&self, node: NodeId, direction: Direction) -> Vec<(NodeId, EdgeId)>;
115
116    /// Returns the out-degree of a node (number of outgoing edges).
117    fn out_degree(&self, node: NodeId) -> usize;
118
119    /// Returns the in-degree of a node (number of incoming edges).
120    fn in_degree(&self, node: NodeId) -> usize;
121
122    /// Whether backward adjacency is available for incoming edge queries.
123    fn has_backward_adjacency(&self) -> bool;
124
125    // --- Scans ---
126
127    /// Returns all non-deleted node IDs, sorted by ID.
128    fn node_ids(&self) -> Vec<NodeId>;
129
130    /// Returns node IDs with a specific label.
131    fn nodes_by_label(&self, label: &str) -> Vec<NodeId>;
132
133    /// Returns the total number of non-deleted nodes.
134    fn node_count(&self) -> usize;
135
136    /// Returns the total number of non-deleted edges.
137    fn edge_count(&self) -> usize;
138
139    // --- Entity metadata ---
140
141    /// Returns the type string of an edge.
142    fn edge_type(&self, id: EdgeId) -> Option<ArcStr>;
143
144    // --- Index introspection ---
145
146    /// Returns `true` if a property index exists for the given property.
147    ///
148    /// The default returns `false`, which is correct for stores without indexes.
149    fn has_property_index(&self, _property: &str) -> bool {
150        false
151    }
152
153    // --- Filtered search ---
154
155    /// Finds all nodes with a specific property value. Uses indexes when available.
156    fn find_nodes_by_property(&self, property: &str, value: &Value) -> Vec<NodeId>;
157
158    /// Finds nodes matching multiple property equality conditions.
159    fn find_nodes_by_properties(&self, conditions: &[(&str, Value)]) -> Vec<NodeId>;
160
161    /// Finds nodes whose property value falls within a range.
162    fn find_nodes_in_range(
163        &self,
164        property: &str,
165        min: Option<&Value>,
166        max: Option<&Value>,
167        min_inclusive: bool,
168        max_inclusive: bool,
169    ) -> Vec<NodeId>;
170
171    // --- Zone maps (skip pruning) ---
172
173    /// Returns `true` if a node property predicate might match any nodes.
174    /// Uses zone maps for early filtering.
175    fn node_property_might_match(
176        &self,
177        property: &PropertyKey,
178        op: CompareOp,
179        value: &Value,
180    ) -> bool;
181
182    /// Returns `true` if an edge property predicate might match any edges.
183    fn edge_property_might_match(
184        &self,
185        property: &PropertyKey,
186        op: CompareOp,
187        value: &Value,
188    ) -> bool;
189
190    // --- Statistics (for cost-based optimizer) ---
191
192    /// Returns the current statistics snapshot (cheap Arc clone).
193    fn statistics(&self) -> Arc<Statistics>;
194
195    /// Estimates cardinality for a label scan.
196    fn estimate_label_cardinality(&self, label: &str) -> f64;
197
198    /// Estimates average degree for an edge type.
199    fn estimate_avg_degree(&self, edge_type: &str, outgoing: bool) -> f64;
200
201    // --- Epoch ---
202
203    /// Returns the current MVCC epoch.
204    fn current_epoch(&self) -> EpochId;
205
206    // --- Schema introspection ---
207
208    /// Returns all label names in the database.
209    fn all_labels(&self) -> Vec<String> {
210        Vec::new()
211    }
212
213    /// Returns all edge type names in the database.
214    fn all_edge_types(&self) -> Vec<String> {
215        Vec::new()
216    }
217
218    /// Returns all property key names used in the database.
219    fn all_property_keys(&self) -> Vec<String> {
220        Vec::new()
221    }
222
223    // --- History ---
224
225    /// Returns all versions of a node with their creation/deletion epochs, newest first.
226    ///
227    /// Each entry is `(created_epoch, deleted_epoch, Node)`. Properties and labels
228    /// reflect the current state (they are not versioned per-epoch).
229    ///
230    /// Default returns empty (not all backends track version history).
231    fn get_node_history(&self, _id: NodeId) -> Vec<(EpochId, Option<EpochId>, Node)> {
232        Vec::new()
233    }
234
235    /// Returns all versions of an edge with their creation/deletion epochs, newest first.
236    ///
237    /// Each entry is `(created_epoch, deleted_epoch, Edge)`. Properties reflect
238    /// the current state (they are not versioned per-epoch).
239    ///
240    /// Default returns empty (not all backends track version history).
241    fn get_edge_history(&self, _id: EdgeId) -> Vec<(EpochId, Option<EpochId>, Edge)> {
242        Vec::new()
243    }
244}
245
246/// Write operations for graph mutation.
247///
248/// Separated from [`GraphStore`] so read-only wrappers (snapshots, read
249/// replicas) can implement only `GraphStore`. Any mutable store is also
250/// readable via the supertrait bound.
251pub trait GraphStoreMut: GraphStore {
252    // --- Node creation ---
253
254    /// Creates a new node with the given labels.
255    fn create_node(&self, labels: &[&str]) -> NodeId;
256
257    /// Creates a new node within a transaction context.
258    fn create_node_versioned(
259        &self,
260        labels: &[&str],
261        epoch: EpochId,
262        transaction_id: TransactionId,
263    ) -> NodeId;
264
265    // --- Edge creation ---
266
267    /// Creates a new edge between two nodes.
268    fn create_edge(&self, src: NodeId, dst: NodeId, edge_type: &str) -> EdgeId;
269
270    /// Creates a new edge within a transaction context.
271    fn create_edge_versioned(
272        &self,
273        src: NodeId,
274        dst: NodeId,
275        edge_type: &str,
276        epoch: EpochId,
277        transaction_id: TransactionId,
278    ) -> EdgeId;
279
280    /// Creates multiple edges in batch (single lock acquisition).
281    fn batch_create_edges(&self, edges: &[(NodeId, NodeId, &str)]) -> Vec<EdgeId>;
282
283    // --- Deletion ---
284
285    /// Deletes a node. Returns `true` if the node existed.
286    fn delete_node(&self, id: NodeId) -> bool;
287
288    /// Deletes a node within a transaction context. Returns `true` if the node existed.
289    fn delete_node_versioned(
290        &self,
291        id: NodeId,
292        epoch: EpochId,
293        transaction_id: TransactionId,
294    ) -> bool;
295
296    /// Deletes all edges connected to a node (DETACH DELETE).
297    fn delete_node_edges(&self, node_id: NodeId);
298
299    /// Deletes an edge. Returns `true` if the edge existed.
300    fn delete_edge(&self, id: EdgeId) -> bool;
301
302    /// Deletes an edge within a transaction context. Returns `true` if the edge existed.
303    fn delete_edge_versioned(
304        &self,
305        id: EdgeId,
306        epoch: EpochId,
307        transaction_id: TransactionId,
308    ) -> bool;
309
310    // --- Property mutation ---
311
312    /// Sets a property on a node.
313    fn set_node_property(&self, id: NodeId, key: &str, value: Value);
314
315    /// Sets a property on an edge.
316    fn set_edge_property(&self, id: EdgeId, key: &str, value: Value);
317
318    /// Removes a property from a node. Returns the previous value if it existed.
319    fn remove_node_property(&self, id: NodeId, key: &str) -> Option<Value>;
320
321    /// Removes a property from an edge. Returns the previous value if it existed.
322    fn remove_edge_property(&self, id: EdgeId, key: &str) -> Option<Value>;
323
324    // --- Label mutation ---
325
326    /// Adds a label to a node. Returns `true` if the label was new.
327    fn add_label(&self, node_id: NodeId, label: &str) -> bool;
328
329    /// Removes a label from a node. Returns `true` if the label existed.
330    fn remove_label(&self, node_id: NodeId, label: &str) -> bool;
331
332    // --- Convenience (with default implementations) ---
333
334    /// Creates a new node with labels and properties in one call.
335    ///
336    /// The default implementation calls [`create_node`](Self::create_node)
337    /// followed by [`set_node_property`](Self::set_node_property) for each
338    /// property. Implementations may override for atomicity or performance.
339    fn create_node_with_props(
340        &self,
341        labels: &[&str],
342        properties: &[(PropertyKey, Value)],
343    ) -> NodeId {
344        let id = self.create_node(labels);
345        for (key, value) in properties {
346            self.set_node_property(id, key.as_str(), value.clone());
347        }
348        id
349    }
350
351    /// Creates a new edge with properties in one call.
352    ///
353    /// The default implementation calls [`create_edge`](Self::create_edge)
354    /// followed by [`set_edge_property`](Self::set_edge_property) for each
355    /// property. Implementations may override for atomicity or performance.
356    fn create_edge_with_props(
357        &self,
358        src: NodeId,
359        dst: NodeId,
360        edge_type: &str,
361        properties: &[(PropertyKey, Value)],
362    ) -> EdgeId {
363        let id = self.create_edge(src, dst, edge_type);
364        for (key, value) in properties {
365            self.set_edge_property(id, key.as_str(), value.clone());
366        }
367        id
368    }
369}
grafeo_core/graph/traits.rs

grafeo_core/graph/
traits.rs
