rust-kgdb 0.3.2 → 0.3.3

package/README.md

@@ -14,7 +14,8 @@
 | Feature | Description |
 |---------|-------------|
 | **GraphDB** | Core RDF/SPARQL database with 100% W3C compliance |
-| **GraphFrames** | Spark-compatible graph analytics (PageRank, triangles, motifs) |
+| **GraphFrames** | Spark-compatible graph analytics (PageRank, triangles, components) |
+| **Motif Finding** | Graph pattern DSL for structural queries (fraud rings, recommendations) |
 | **EmbeddingService** | Vector similarity search, text search, multi-provider embeddings |
 | **Embedding Triggers** | Automatic embedding generation on INSERT/UPDATE/DELETE |
 | **Embedding Providers** | OpenAI, Voyage, Cohere, Anthropic, Mistral, Jina, Ollama, HF-TEI |
@@ -140,6 +141,121 @@ console.log('Star graph:', star.vertexCount(), 'vertices,', star.edgeCount(), 'e
 console.log('Cycle graph:', cycle.vertexCount(), 'vertices,', cycle.edgeCount(), 'edges')
 ```
 
+### 2b. Motif Pattern Matching (Graph Pattern DSL)
+
+Motifs are recurring structural patterns in graphs. rust-kgdb supports a powerful DSL for finding motifs:
+
+```javascript
+const { GraphFrame, completeGraph, chainGraph, cycleGraph, friendsGraph } = require('rust-kgdb')
+
+// === Basic Motif Syntax ===
+// (a)-[]->(b)              Single edge from a to b
+// (a)-[e]->(b)             Named edge 'e' from a to b
+// (a)-[]->(b); (b)-[]->(c) Two-hop path (chain pattern)
+// !(a)-[]->(b)             Negation (edge does NOT exist)
+
+// === Find Single Edges ===
+const chain = chainGraph(5)  // v0 -> v1 -> v2 -> v3 -> v4
+const edges = JSON.parse(chain.find("(a)-[]->(b)"))
+console.log('All edges:', edges.length)  // 4
+
+// === Two-Hop Paths (Friend-of-Friend Pattern) ===
+const twoHop = JSON.parse(chain.find("(a)-[]->(b); (b)-[]->(c)"))
+console.log('Two-hop paths:', twoHop.length)  // 3
+// v0->v1->v2, v1->v2->v3, v2->v3->v4
+
+// === Three-Hop Paths ===
+const threeHop = JSON.parse(chain.find("(a)-[]->(b); (b)-[]->(c); (c)-[]->(d)"))
+console.log('Three-hop paths:', threeHop.length)  // 2
+
+// === Triangle Pattern (Cycle of Length 3) ===
+const k4 = completeGraph(4)  // K4 has triangles
+const triangles = JSON.parse(k4.find("(a)-[]->(b); (b)-[]->(c); (c)-[]->(a)"))
+// Filter to avoid counting same triangle multiple times
+const uniqueTriangles = triangles.filter(t => t.a < t.b && t.b < t.c)
+console.log('Triangles in K4:', uniqueTriangles.length)  // 4
+
+// === Star Pattern (Hub with Multiple Spokes) ===
+const social = new GraphFrame(
+  JSON.stringify([
+    {id: "influencer"},
+    {id: "follower1"}, {id: "follower2"}, {id: "follower3"}
+  ]),
+  JSON.stringify([
+    {src: "influencer", dst: "follower1"},
+    {src: "influencer", dst: "follower2"},
+    {src: "influencer", dst: "follower3"}
+  ])
+)
+// Find hub pattern: someone with 2+ outgoing edges
+const hubPattern = JSON.parse(social.find("(hub)-[]->(f1); (hub)-[]->(f2)"))
+console.log('Hub patterns (2+ followers):', hubPattern.length)
+
+// === Reciprocal Relationship (Mutual Friends) ===
+const mutual = new GraphFrame(
+  JSON.stringify([{id: "alice"}, {id: "bob"}, {id: "carol"}]),
+  JSON.stringify([
+    {src: "alice", dst: "bob"},
+    {src: "bob", dst: "alice"},  // Reciprocal
+    {src: "bob", dst: "carol"}   // One-way
+  ])
+)
+const reciprocal = JSON.parse(mutual.find("(a)-[]->(b); (b)-[]->(a)"))
+console.log('Mutual relationships:', reciprocal.length)  // 2 (alice<->bob counted twice)
+
+// === Diamond Pattern (Common in Fraud Detection) ===
+// A -> B, A -> C, B -> D, C -> D (convergence point D)
+const diamond = new GraphFrame(
+  JSON.stringify([{id: "A"}, {id: "B"}, {id: "C"}, {id: "D"}]),
+  JSON.stringify([
+    {src: "A", dst: "B"},
+    {src: "A", dst: "C"},
+    {src: "B", dst: "D"},
+    {src: "C", dst: "D"}
+  ])
+)
+const diamondPattern = JSON.parse(diamond.find(
+  "(a)-[]->(b); (a)-[]->(c); (b)-[]->(d); (c)-[]->(d)"
+))
+console.log('Diamond patterns:', diamondPattern.length)  // 1
+
+// === Use Case: Fraud Ring Detection ===
+// Find circular money transfers: A -> B -> C -> A
+const transactions = new GraphFrame(
+  JSON.stringify([
+    {id: "acc001"}, {id: "acc002"}, {id: "acc003"}, {id: "acc004"}
+  ]),
+  JSON.stringify([
+    {src: "acc001", dst: "acc002", amount: 10000},
+    {src: "acc002", dst: "acc003", amount: 9900},
+    {src: "acc003", dst: "acc001", amount: 9800},  // Suspicious cycle!
+    {src: "acc003", dst: "acc004", amount: 5000}   // Normal transfer
+  ])
+)
+const cycles = JSON.parse(transactions.find(
+  "(a)-[]->(b); (b)-[]->(c); (c)-[]->(a)"
+))
+console.log('Circular transfer patterns:', cycles.length)  // Found fraud ring!
+
+// === Use Case: Recommendation (Friends-of-Friends not yet connected) ===
+const network = friendsGraph()
+const fofPattern = JSON.parse(network.find("(a)-[]->(b); (b)-[]->(c)"))
+// Filter: a != c and no direct edge a->c (potential recommendation)
+console.log('Friend-of-friend patterns for recommendations:', fofPattern.length)
+```
+
+### Motif Pattern Reference
+
+| Pattern | DSL Syntax | Description |
+|---------|------------|-------------|
+| **Edge** | `(a)-[]->(b)` | Single directed edge |
+| **Named Edge** | `(a)-[e]->(b)` | Edge with binding name |
+| **Two-hop** | `(a)-[]->(b); (b)-[]->(c)` | Path of length 2 |
+| **Triangle** | `(a)-[]->(b); (b)-[]->(c); (c)-[]->(a)` | 3-cycle |
+| **Star** | `(h)-[]->(a); (h)-[]->(b); (h)-[]->(c)` | Hub pattern |
+| **Diamond** | `(a)-[]->(b); (a)-[]->(c); (b)-[]->(d); (c)-[]->(d)` | Convergence |
+| **Negation** | `!(a)-[]->(b)` | Edge must NOT exist |
+
 ### 3. EmbeddingService (Vector Similarity & Text Search)
 
 ```javascript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rust-kgdb",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "High-performance RDF/SPARQL database with GraphFrames analytics, vector embeddings, Datalog reasoning, and Pregel BSP processing",
   "main": "index.js",
   "types": "index.d.ts",