| name | neumann-graph |
| description | Model and query graph data in Neumann. Use when creating nodes and edges, traversing relationships, finding paths, running graph algorithms, or using Cypher-style queries. |
Neumann Graph Engine Guide
Graph Model
Neumann implements a directed property graph stored in tensor_store's graph
tensor slab. Key concepts:
- Nodes have a label (type) and a property map (
{ key: value }).
- Edges are directed (from -> to), have a type label, and a property map.
- Node/edge IDs are auto-generated strings returned on creation.
- Direction keywords are
OUTGOING, INCOMING, BOTH. Never use OUT, IN, or UNDIRECTED.
The graph slab uses sharded locking -- concurrent reads and writes to different
nodes/edges proceed in parallel.
CRUD Operations
Nodes
Create a node with label and properties:
NODE CREATE person { name: 'Alice', age: 30, role: 'engineer' }
Returns: the auto-generated node ID (e.g., node-a1b2c3).
Get a node by ID:
NODE GET 'node-a1b2c3'
Delete a node:
NODE DELETE 'node-a1b2c3'
List nodes (optional label filter, limit, offset):
NODE LIST
NODE LIST person
NODE LIST person LIMIT 10
NODE LIST person LIMIT 10 OFFSET 20
Edges
Create an edge between two nodes:
EDGE CREATE 'node-1' -> 'node-2' : knows { since: 2024, weight: 0.9 }
The -> arrow and : type delimiter are required syntax. Properties are optional.
Get an edge by ID:
EDGE GET 'edge-xyz'
Delete an edge:
EDGE DELETE 'edge-xyz'
List edges (optional type filter):
EDGE LIST
EDGE LIST knows
EDGE LIST knows LIMIT 50 OFFSET 10
Batch operations
Batch create nodes:
GRAPH BATCH CREATE NODES [(:person {name: 'Alice'}), (:person {name: 'Bob'}), (:company {name: 'Acme'})]
Batch create edges:
GRAPH BATCH CREATE EDGES [('node-1' -> 'node-2' : knows {since: 2024}), ('node-2' -> 'node-3' : works_at)]
Batch delete:
GRAPH BATCH DELETE NODES ['node-1', 'node-2']
GRAPH BATCH DELETE EDGES ['edge-1', 'edge-2']
Batch update nodes:
GRAPH BATCH UPDATE NODES [('node-1' {age: 31}), ('node-2' {age: 26})]
Traversal and Paths
NEIGHBORS
Find nodes adjacent to a given node.
NEIGHBORS 'node-1' OUTGOING
NEIGHBORS 'node-1' INCOMING
NEIGHBORS 'node-1' BOTH
With edge type filter:
NEIGHBORS 'node-1' OUTGOING knows
Cross-engine: neighbors ranked by vector similarity:
NEIGHBORS 'node-1' BOTH BY SIMILARITY [0.1, 0.2, 0.3] LIMIT 5
PATH: shortest path (BFS)
PATH SHORTEST 'node-a' 'node-z'
Returns a list of node IDs forming the shortest unweighted path.
PATH: all paths
PATH ALL 'node-a' 'node-z' MAX_DEPTH 5
PATH: weighted shortest (Dijkstra)
PATH WEIGHTED 'node-a' 'node-z' WEIGHT distance
Uses the distance edge property as the weight.
PATH: all weighted paths
PATH ALL_WEIGHTED 'node-a' 'node-z' WEIGHT cost MAX_DEPTH 4
PATH: variable-length
PATH VARIABLE 'node-a' 'node-z' MIN_DEPTH 2 MAX_DEPTH 5
Finds paths with length between MIN_DEPTH and MAX_DEPTH hops.
Graph Algorithms
All algorithms accept optional DIRECTION (OUTGOING/INCOMING/BOTH) and
edge type filters.
PageRank
GRAPH PAGERANK
GRAPH PAGERANK DAMPING 0.85 TOLERANCE 0.001 ITERATIONS 100
GRAPH PAGERANK OUTGOING knows
Result type: PageRank (node ID + score pairs).
Betweenness centrality
GRAPH BETWEENNESS CENTRALITY
GRAPH BETWEENNESS CENTRALITY SAMPLING 0.5 OUTGOING
SAMPLING controls the fraction of node pairs sampled (0.0-1.0). Lower values
are faster but less accurate.
Closeness centrality
GRAPH CLOSENESS CENTRALITY
GRAPH CLOSENESS CENTRALITY INCOMING knows
Eigenvector centrality
GRAPH EIGENVECTOR CENTRALITY
GRAPH EIGENVECTOR CENTRALITY ITERATIONS 100 TOLERANCE 0.001
Community detection: Louvain
GRAPH LOUVAIN COMMUNITIES
GRAPH LOUVAIN COMMUNITIES RESOLUTION 1.0 PASSES 10 BOTH
Higher RESOLUTION produces smaller communities.
Community detection: Label Propagation
GRAPH LABEL PROPAGATION
GRAPH LABEL PROPAGATION ITERATIONS 100 OUTGOING
Advanced Features
Constraints
GRAPH CONSTRAINT CREATE unique_name ON NODE person PROPERTY email UNIQUE
GRAPH CONSTRAINT CREATE exists_name ON NODE person PROPERTY name EXISTS
GRAPH CONSTRAINT CREATE type_age ON NODE person PROPERTY age TYPE 'integer'
GRAPH CONSTRAINT DROP unique_name
GRAPH CONSTRAINT LIST
GRAPH CONSTRAINT GET unique_name
Graph indexes
GRAPH INDEX CREATE NODE PROPERTY name
GRAPH INDEX CREATE EDGE PROPERTY weight
GRAPH INDEX CREATE LABEL
GRAPH INDEX CREATE EDGE TYPE
GRAPH INDEX DROP NODE name
GRAPH INDEX DROP EDGE weight
GRAPH INDEX SHOW NODE
GRAPH INDEX SHOW EDGE
Aggregation
GRAPH AGGREGATE COUNT NODES
GRAPH AGGREGATE COUNT NODES person
GRAPH AGGREGATE COUNT EDGES
GRAPH AGGREGATE COUNT EDGES knows
GRAPH AGGREGATE SUM NODE PROPERTY age person
GRAPH AGGREGATE AVG NODE PROPERTY age WHERE age > 18
GRAPH AGGREGATE MIN EDGE PROPERTY weight
GRAPH AGGREGATE MAX EDGE PROPERTY cost knows
Supported functions: COUNT, SUM, AVG, MIN, MAX.
Pattern matching
GRAPH PATTERN MATCH (a:person)-[:knows]->(b:person) LIMIT 10
GRAPH PATTERN COUNT (a)-[:works_at]->(b:company)
GRAPH PATTERN EXISTS (a:person)-[:knows]->(b)
Pattern syntax uses (variable:Label) for nodes and [:TYPE] for edges.
Cypher (Experimental)
Neumann supports a subset of Cypher for graph queries.
MATCH
MATCH (p:person)-[r:knows]->(q:person) WHERE p.age > 25 RETURN p.name, q.name LIMIT 10
OPTIONAL MATCH (n)-[r]->(m) RETURN n, r, m
CREATE
CREATE (n:person {name: 'Alice', age: 30})-[:knows]->(m:person {name: 'Bob'})
MERGE
MERGE (n:person {email: 'alice@example.com'}) ON CREATE SET n.name = 'Alice' ON MATCH SET n.last_seen = '2024-01-01'
DELETE
DELETE n
DETACH DELETE n
DETACH DELETE removes the node and all its edges.
Variable-length relationships
MATCH (a)-[*1..3]->(b) RETURN a, b
MATCH (a:person)-[:knows*1..5]->(b:person) RETURN a.name, b.name
Direction Gotcha
This is the most common mistake when writing graph queries. The parser uses
OUTGOING, INCOMING, and BOTH as direction keywords.
NEIGHBORS 'n1' OUTGOING
NEIGHBORS 'n1' OUT
NEIGHBORS 'n1' IN
NEIGHBORS 'n1' UNDIRECTED
The same applies to algorithm direction filters:
GRAPH PAGERANK OUTGOING
GRAPH PAGERANK OUT
