Graph Database

Nucleus includes a native property graph engine with Cypher query support, graph algorithms, and CSR-optimized traversals — no separate graph database needed.

Creating Nodes & Edges

-- Add nodes with labels and properties
SELECT GRAPH_ADD_NODE('Person', '{"name": "Alice", "age": 30}');
-- → 1
SELECT GRAPH_ADD_NODE('Person', '{"name": "Bob", "age": 25}');
-- → 2
SELECT GRAPH_ADD_NODE('Company', '{"name": "Acme", "industry": "Tech"}');
-- → 3

-- Add directed edges with types and properties
SELECT GRAPH_ADD_EDGE(1, 2, 'KNOWS', '{"since": 2020}');
SELECT GRAPH_ADD_EDGE(1, 3, 'WORKS_AT', '{"role": "Engineer"}');
SELECT GRAPH_ADD_EDGE(2, 3, 'WORKS_AT', '{"role": "Designer"}');

Querying the Graph

Neighbors

-- Outgoing neighbors (default)
SELECT GRAPH_NEIGHBORS(1, 'out');
-- → [{"neighbor_id":2,"edge_id":1,"edge_type":"KNOWS"}, ...]

-- Incoming neighbors
SELECT GRAPH_NEIGHBORS(3, 'in');

-- Both directions
SELECT GRAPH_NEIGHBORS(1, 'both');

Shortest Path

-- Find shortest path between two nodes
SELECT GRAPH_SHORTEST_PATH(1, 3);
-- → [1, 3]  (direct edge exists)

Statistics

SELECT GRAPH_NODE_COUNT();  -- → 3
SELECT GRAPH_EDGE_COUNT();  -- → 3

Cypher Queries

Use GRAPH_QUERY for pattern matching with the Cypher query language:

-- Find all people
SELECT GRAPH_QUERY('MATCH (p:Person) RETURN p.name, p.age');

-- Traverse relationships
SELECT GRAPH_QUERY('
  MATCH (p:Person)-[:WORKS_AT]->(c:Company)
  RETURN p.name, c.name
');

-- Filter with WHERE
SELECT GRAPH_QUERY('
  MATCH (p:Person)-[r:KNOWS]->(q:Person)
  WHERE p.age > 25
  RETURN p.name, q.name
');

-- Create nodes and edges
SELECT GRAPH_QUERY('
  CREATE (n:City {name: "Portland", state: "OR"})
');

SELECT GRAPH_QUERY('
  CREATE (a:Person {name: "Charlie"})-[:KNOWS]->(b:Person {name: "Diana"})
');

Supported Cypher Features

| Feature | Example | |---------|---------| | Pattern matching | MATCH (a)-[r]->(b) | | Labels | (n:Person) | | Properties | {name: "Alice"} | | Edge types | -[:KNOWS]-> | | Directions | ->, <-, -- (undirected) | | Variable-length paths | -[*1..3]-> | | WHERE | WHERE n.age > 25 AND n.name = "Alice" | | OPTIONAL MATCH | Returns NULL if no match | | WITH | Intermediate projection | | DELETE | DELETE n, r | | COUNT | RETURN COUNT(*) |

Graph Algorithms

Built-in algorithms accessible through the graph engine:

| Algorithm | Purpose | |-----------|---------| | BFS | Breadth-first traversal | | DFS | Depth-first traversal | | Shortest Path | Unweighted (BFS-based) | | Dijkstra | Weighted shortest path using edge properties | | Connected Components | Find isolated subgraphs | | PageRank | Rank nodes by importance | | Label Propagation | Community detection | | Louvain | Modularity-optimized community detection |

Deleting Graph Data

-- Delete a node (cascades connected edges)
SELECT GRAPH_DELETE_NODE(1);

-- Delete an edge
SELECT GRAPH_DELETE_EDGE(1);

-- Delete via Cypher
SELECT GRAPH_QUERY('
  MATCH (n:Person {name: "Bob"})
  DELETE n
');

Performance

• CSR (Compressed Sparse Row) format for cache-friendly analytical traversals
• Property indexes (B-tree) per label/property for fast lookups
• Label and type indexes for O(1) filtered traversals
• Parallel BFS for multi-source traversals
• Tiered storage with hot/cold separation (100K node threshold)
• WAL-backed durability with crash recovery

Use Cases

• Social networks — Friends, followers, mutual connections
• Knowledge graphs — Entity relationships, ontologies
• Fraud detection — Transaction paths, ring detection
• Recommendation engines — User-item-category graphs
• Network topology — Infrastructure dependencies