|
| 1 | +//! `graph_gremlin` — a minimal Gremlin-style traversal over a [`GraphSnapshot`]. |
| 2 | +//! |
| 3 | +//! The pure-Rust contrast to the DataFusion node/edge tables ([`crate::graph_table`], |
| 4 | +//! `query-lite`): `g(&snap).v(&["id"]).out().to_vec()` walks the adjacency in the |
| 5 | +//! snapshot with **zero SQL, zero DataFusion** — just the `source → target` edge |
| 6 | +//! list. A "very basic Gremlin POC": `V` / `out` / `in_` / `out_e(label)` / |
| 7 | +//! `in_e(label)` / `values_kind` / `to_vec` / `count`. |
| 8 | +//! |
| 9 | +//! SurrealQL graph traversal lowers to the SAME steps — `->edge->` ≈ [`out`], |
| 10 | +//! `<-edge<-` ≈ [`in_`], `->edge(WHERE ...)->` ≈ [`out_e`] — so this doubles as |
| 11 | +//! the SurrealQL traversal kernel over the family-adapter graph. Both consume the |
| 12 | +//! `GraphSnapshot` the SoA projector ([`lance_graph_contract::soa_graph`]) |
| 13 | +//! produces from the 32-byte node head; the family nodes are the stable hubs the |
| 14 | +//! traversal hops through. |
| 15 | +//! |
| 16 | +//! [`out`]: Traversal::out |
| 17 | +//! [`in_`]: Traversal::in_ |
| 18 | +//! [`out_e`]: Traversal::out_e |
| 19 | +
|
| 20 | +use lance_graph_contract::graph_render::GraphSnapshot; |
| 21 | +use std::collections::HashSet; |
| 22 | + |
| 23 | +/// The Gremlin `g` — a traversal source bound to one graph snapshot. |
| 24 | +pub struct GraphTraversalSource<'a> { |
| 25 | + snap: &'a GraphSnapshot, |
| 26 | +} |
| 27 | + |
| 28 | +/// `g(&snap)` — open a traversal over the snapshot (the Gremlin `g`). |
| 29 | +pub fn g(snap: &GraphSnapshot) -> GraphTraversalSource<'_> { |
| 30 | + GraphTraversalSource { snap } |
| 31 | +} |
| 32 | + |
| 33 | +impl<'a> GraphTraversalSource<'a> { |
| 34 | + /// `g.V(ids)` — seed the traversal at the given vertex ids. An empty slice is |
| 35 | + /// `g.V()` (all vertices). |
| 36 | + pub fn v(&self, ids: &[&str]) -> Traversal<'a> { |
| 37 | + let current: Vec<String> = if ids.is_empty() { |
| 38 | + self.snap.nodes.iter().map(|n| n.id.clone()).collect() |
| 39 | + } else { |
| 40 | + ids.iter().map(|s| s.to_string()).collect() |
| 41 | + }; |
| 42 | + Traversal { |
| 43 | + snap: self.snap, |
| 44 | + current, |
| 45 | + } |
| 46 | + } |
| 47 | +} |
| 48 | + |
| 49 | +/// An in-flight traversal: the multiset of vertex ids currently held, plus the |
| 50 | +/// snapshot to hop over. Steps consume `self` and return `Self` (Gremlin fluent). |
| 51 | +pub struct Traversal<'a> { |
| 52 | + snap: &'a GraphSnapshot, |
| 53 | + current: Vec<String>, |
| 54 | +} |
| 55 | + |
| 56 | +impl<'a> Traversal<'a> { |
| 57 | + /// `out()` — follow outgoing edges (`source ∈ current → target`), any label. |
| 58 | + #[must_use] |
| 59 | + pub fn out(mut self) -> Self { |
| 60 | + self.step(None, true); |
| 61 | + self |
| 62 | + } |
| 63 | + |
| 64 | + /// `out(label)` — outgoing edges whose label equals `label`. |
| 65 | + #[must_use] |
| 66 | + pub fn out_e(mut self, label: &str) -> Self { |
| 67 | + self.step(Some(label), true); |
| 68 | + self |
| 69 | + } |
| 70 | + |
| 71 | + /// `in()` — follow incoming edges (`target ∈ current → source`), any label. |
| 72 | + #[must_use] |
| 73 | + pub fn in_(mut self) -> Self { |
| 74 | + self.step(None, false); |
| 75 | + self |
| 76 | + } |
| 77 | + |
| 78 | + /// `in(label)` — incoming edges whose label equals `label`. |
| 79 | + #[must_use] |
| 80 | + pub fn in_e(mut self, label: &str) -> Self { |
| 81 | + self.step(Some(label), false); |
| 82 | + self |
| 83 | + } |
| 84 | + |
| 85 | + fn step(&mut self, label: Option<&str>, outgoing: bool) { |
| 86 | + let cur: HashSet<&str> = self.current.iter().map(String::as_str).collect(); |
| 87 | + let mut next: Vec<String> = Vec::new(); |
| 88 | + let mut seen: HashSet<String> = HashSet::new(); |
| 89 | + for e in &self.snap.edges { |
| 90 | + if let Some(l) = label { |
| 91 | + if e.label != l { |
| 92 | + continue; |
| 93 | + } |
| 94 | + } |
| 95 | + let (from, to) = if outgoing { |
| 96 | + (&e.source, &e.target) |
| 97 | + } else { |
| 98 | + (&e.target, &e.source) |
| 99 | + }; |
| 100 | + if cur.contains(from.as_str()) && seen.insert(to.clone()) { |
| 101 | + next.push(to.clone()); |
| 102 | + } |
| 103 | + } |
| 104 | + self.current = next; |
| 105 | + } |
| 106 | + |
| 107 | + /// Terminal `values("kind")` — project the `kind` of each reached vertex |
| 108 | + /// (skips ids that are not present as nodes, e.g. a dangling adapter target). |
| 109 | + #[must_use] |
| 110 | + pub fn values_kind(&self) -> Vec<String> { |
| 111 | + self.current |
| 112 | + .iter() |
| 113 | + .filter_map(|id| { |
| 114 | + self.snap |
| 115 | + .nodes |
| 116 | + .iter() |
| 117 | + .find(|n| &n.id == id) |
| 118 | + .map(|n| n.kind.clone()) |
| 119 | + }) |
| 120 | + .collect() |
| 121 | + } |
| 122 | + |
| 123 | + /// Terminal `toList()` — the vertex ids currently reached. |
| 124 | + #[must_use] |
| 125 | + pub fn to_vec(self) -> Vec<String> { |
| 126 | + self.current |
| 127 | + } |
| 128 | + |
| 129 | + /// Terminal `count()` — number of vertices reached. |
| 130 | + #[must_use] |
| 131 | + pub fn count(self) -> usize { |
| 132 | + self.current.len() |
| 133 | + } |
| 134 | +} |
| 135 | + |
| 136 | +#[cfg(test)] |
| 137 | +mod tests { |
| 138 | + use super::*; |
| 139 | + use lance_graph_contract::graph_render::{RenderEdge, RenderNode}; |
| 140 | + |
| 141 | + fn node(id: &str, kind: &str) -> RenderNode { |
| 142 | + RenderNode { |
| 143 | + id: id.to_string(), |
| 144 | + label: id.to_string(), |
| 145 | + kind: kind.to_string(), |
| 146 | + confidence: 1.0, |
| 147 | + props: vec![], |
| 148 | + } |
| 149 | + } |
| 150 | + fn edge(source: &str, target: &str, label: &str) -> RenderEdge { |
| 151 | + RenderEdge { |
| 152 | + source: source.to_string(), |
| 153 | + target: target.to_string(), |
| 154 | + label: label.to_string(), |
| 155 | + frequency: 1.0, |
| 156 | + confidence: 1.0, |
| 157 | + inferred: false, |
| 158 | + } |
| 159 | + } |
| 160 | + |
| 161 | + fn sample() -> GraphSnapshot { |
| 162 | + // A -knows-> B -knows-> C ; A -member-of-> family:00000a |
| 163 | + GraphSnapshot { |
| 164 | + nodes: vec![ |
| 165 | + node("A", "Person"), |
| 166 | + node("B", "Person"), |
| 167 | + node("C", "Person"), |
| 168 | + node("family:00000a", "Family"), |
| 169 | + ], |
| 170 | + edges: vec![ |
| 171 | + edge("A", "B", "knows"), |
| 172 | + edge("B", "C", "knows"), |
| 173 | + edge("A", "family:00000a", "member-of"), |
| 174 | + ], |
| 175 | + inferences: vec![], |
| 176 | + contradictions: vec![], |
| 177 | + timestamp: 0, |
| 178 | + } |
| 179 | + } |
| 180 | + |
| 181 | + #[test] |
| 182 | + fn out_follows_outgoing_edges() { |
| 183 | + let s = sample(); |
| 184 | + assert_eq!(g(&s).v(&["A"]).out().to_vec(), vec!["B", "family:00000a"]); |
| 185 | + } |
| 186 | + |
| 187 | + #[test] |
| 188 | + fn in_follows_incoming_edges() { |
| 189 | + let s = sample(); |
| 190 | + assert_eq!(g(&s).v(&["B"]).in_().to_vec(), vec!["A".to_string()]); |
| 191 | + } |
| 192 | + |
| 193 | + #[test] |
| 194 | + fn out_e_filters_by_label() { |
| 195 | + let s = sample(); |
| 196 | + // g.V("A").out("knows") = [B]; out("member-of") = [family:00000a] |
| 197 | + assert_eq!(g(&s).v(&["A"]).out_e("knows").to_vec(), vec!["B"]); |
| 198 | + assert_eq!( |
| 199 | + g(&s).v(&["A"]).out_e("member-of").to_vec(), |
| 200 | + vec!["family:00000a"] |
| 201 | + ); |
| 202 | + } |
| 203 | + |
| 204 | + #[test] |
| 205 | + fn two_hop_traversal() { |
| 206 | + let s = sample(); |
| 207 | + // g.V("A").out("knows").out("knows") = [C] |
| 208 | + assert_eq!( |
| 209 | + g(&s).v(&["A"]).out_e("knows").out_e("knows").to_vec(), |
| 210 | + vec!["C"] |
| 211 | + ); |
| 212 | + } |
| 213 | + |
| 214 | + #[test] |
| 215 | + fn values_kind_projects_node_property() { |
| 216 | + let s = sample(); |
| 217 | + // A's "member-of" neighbour is the family hub → kind "Family". |
| 218 | + assert_eq!(g(&s).v(&["A"]).out_e("member-of").values_kind(), vec!["Family"]); |
| 219 | + } |
| 220 | + |
| 221 | + #[test] |
| 222 | + fn unknown_label_yields_empty() { |
| 223 | + let s = sample(); |
| 224 | + assert_eq!(g(&s).v(&["A"]).out_e("nope").count(), 0); |
| 225 | + } |
| 226 | + |
| 227 | + #[test] |
| 228 | + fn v_with_no_seed_is_all_vertices() { |
| 229 | + let s = sample(); |
| 230 | + assert_eq!(g(&s).v(&[]).count(), 4); |
| 231 | + } |
| 232 | +} |
0 commit comments