Graph algorithms
Graph algorithms run inside the engine as CALL algo.<name>(…). Each one
yields one row per node (or one row per reachable target), so you compose it
with MATCH, WITH, ORDER BY and RETURN like any other query. They are
exact (no sampling), deterministic, and honour the query timeout.
The examples use this graph:
CREATE (a:Person {name: 'Alice'}), (b:Person {name: 'Bob'}), (c:Person {name: 'Carol'}), (d:Person {name: 'Dave'}), (e:Person {name: 'Eve'}), (a)-[:KNOWS {weight: 1.0}]->(b), (b)-[:KNOWS {weight: 1.0}]->(c), (c)-[:KNOWS {weight: 5.0}]->(a), (a)-[:KNOWS {weight: 9.0}]->(c), (d)-[:KNOWS {weight: 1.0}]->(e)Calling an algorithm
CALL algo.pagerank() YIELD node_id, scoreMATCH (n:Person) WHERE id(n) = id(node_id)RETURN n.name AS name, scoreORDER BY score DESC{name: 'Carol', score: 0.408…}{name: 'Alice', score: 0.390…}{name: 'Eve', score: 0.081…}{name: 'Bob', score: 0.077…}{name: 'Dave', score: 0.044…}Rules that apply to every algo.* call:
- The
CALLmust be the first clause of the query. Pass inputs (such as a source node id) as parameters rather than from an earlierMATCH. node_idis a node reference without its properties. Join it back withMATCH (n) WHERE id(n) = id(node_id)to read properties, as above.- Filter on a yielded column with a following
WITH … WHERE(YIELD … WHEREis not supported). - Options go in a single map argument. An option the algorithm does not read is an error that lists the allowed ones.
Projections
Every algorithm accepts three projection options that select the subgraph it runs on:
| Option | Default | Meaning |
|---|---|---|
labels | all nodes | Only nodes with one of these labels (the induced subgraph). |
edge_types | all types | Only these relationship types. |
direction | 'natural' | 'natural' (stored direction), 'reverse' or 'undirected'. |
CALL algo.pagerank({labels: ['Person'], edge_types: ['KNOWS'], direction: 'undirected', damping: 0.9})YIELD node_id, scoreRETURN node_id, score ORDER BY score DESC LIMIT 10Reference
| Procedure | Yields | Options (besides projections) |
|---|---|---|
algo.pagerank | node_id, score | damping (0.85), max_iterations (100), tolerance (1e-6) |
algo.wcc | node_id, component | — |
algo.scc | node_id, component | — |
algo.degree | node_id, in_degree, out_degree, degree | — |
algo.triangle_count | node_id, triangles, coefficient | — |
algo.label_propagation | node_id, community | max_iterations (10) |
algo.louvain | node_id, community | max_levels (10), max_iterations (10), tolerance (1e-4) |
algo.betweenness | node_id, score | — |
algo.shortest_path | node_id, distance, hops, path | source (required), target, weighted (false) |
algo.fastRP | node_id, embedding | dimension (256), iterations, iteration_weights ([0.0, 1.0, 1.0, 1.0]), normalization_strength (0.0), seed (42) |
Connected components
wcc treats the graph as undirected (weakly connected components); scc
follows directions (strongly connected components, i.e. directed cycles).
Component ids are deterministic.
CALL algo.wcc() YIELD node_id, componentMATCH (n) WHERE id(n) = id(node_id)RETURN component, collect(n.name) AS members ORDER BY component// {component: 0, members: ['Alice', 'Bob', 'Carol']}// {component: 1, members: ['Dave', 'Eve']}Degree
CALL algo.degree() YIELD node_id, in_degree, out_degree, degreeMATCH (n) WHERE id(n) = id(node_id)RETURN n.name AS name, in_degree, out_degree, degreeORDER BY degree DESC, name LIMIT 2// {name: 'Alice', in_degree: 1, out_degree: 2, degree: 3}// {name: 'Carol', in_degree: 2, out_degree: 1, degree: 3}Triangles and clustering
CALL algo.triangle_count({direction: 'undirected'}) YIELD node_id, triangles, coefficientMATCH (n) WHERE id(n) = id(node_id)RETURN n.name AS name, triangles, coefficient ORDER BY name// Alice, Bob and Carol: 1 triangle, coefficient 1.0; Dave and Eve: 0Communities
label_propagation is fast and approximate; louvain optimises modularity.
CALL algo.louvain() YIELD node_id, communityRETURN count(DISTINCT community) AS communities// {communities: 2}Betweenness
Brandes betweenness centrality, exact:
CALL algo.betweenness() YIELD node_id, scoreMATCH (n) WHERE id(n) = id(node_id)RETURN n.name AS name, score ORDER BY score DESC LIMIT 1// {name: 'Alice', score: 1.0}Shortest path
source and target are node ids (the strings id(n) returns), usually
passed as parameters. Without a target, the call returns the distance to
every node reachable from the source (BFS hops; path is null):
CALL algo.shortest_path({source: $alice}) YIELD node_id, distance, hopsMATCH (n) WHERE id(n) = id(node_id)RETURN n.name AS name, distance, hops ORDER BY hops, name// {name: 'Alice', distance: 0.0, hops: 0}// {name: 'Bob', distance: 1.0, hops: 1}// {name: 'Carol', distance: 1.0, hops: 1}With a target it returns one row, or none when the target is unreachable,
and path holds the node sequence with labels and properties:
CALL algo.shortest_path({source: $alice, target: $carol}) YIELD distance, hops, pathRETURN distance, hops, [n IN path | n.name] AS route// {distance: 1.0, hops: 1, route: ['Alice', 'Carol']}weighted: true runs Dijkstra over the numeric weight property of each
relationship:
CALL algo.shortest_path({source: $alice, target: $carol, weighted: true})YIELD distance, hops, pathRETURN distance, hops, [n IN path | n.name] AS route// {distance: 2.0, hops: 2, route: ['Alice', 'Bob', 'Carol']}For a path between two nodes you already matched, Cypher’s
shortestPath(…) is the
pattern form.
FastRP embeddings
FastRP computes structural node embeddings from graph shape alone, with no model or external service. The output is a vector you can store and search with a vector index to find structurally similar nodes.
CALL algo.fastRP({dimension: 8, iterations: 3, seed: 42}) YIELD node_id, embeddingRETURN size(embedding) AS dim, count(*) AS nodes// {dim: 8, nodes: 5}The same (graph, options, seed) always produces the same embeddings.
Cost
Algorithms other than a targeted shortest_path build the projected graph in
memory and visit all of it, so their cost grows with the projection’s size.
Narrow it with labels and edge_types, and raise --query-timeout on the
server for large graphs. A targeted shortest_path in the natural direction
reads only the part of the graph it explores.
AI agents can run the same algorithms through the MCP graph_algorithm tool;
see MCP server.