Skip to content

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, score
MATCH (n:Person) WHERE id(n) = id(node_id)
RETURN n.name AS name, score
ORDER 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 CALL must be the first clause of the query. Pass inputs (such as a source node id) as parameters rather than from an earlier MATCH.
  • node_id is a node reference without its properties. Join it back with MATCH (n) WHERE id(n) = id(node_id) to read properties, as above.
  • Filter on a yielded column with a following WITH … WHERE (YIELD … WHERE is 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:

OptionDefaultMeaning
labelsall nodesOnly nodes with one of these labels (the induced subgraph).
edge_typesall typesOnly 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, score
RETURN node_id, score ORDER BY score DESC LIMIT 10

Reference

ProcedureYieldsOptions (besides projections)
algo.pageranknode_id, scoredamping (0.85), max_iterations (100), tolerance (1e-6)
algo.wccnode_id, component—
algo.sccnode_id, component—
algo.degreenode_id, in_degree, out_degree, degree—
algo.triangle_countnode_id, triangles, coefficient—
algo.label_propagationnode_id, communitymax_iterations (10)
algo.louvainnode_id, communitymax_levels (10), max_iterations (10), tolerance (1e-4)
algo.betweennessnode_id, score—
algo.shortest_pathnode_id, distance, hops, pathsource (required), target, weighted (false)
algo.fastRPnode_id, embeddingdimension (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, component
MATCH (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, degree
MATCH (n) WHERE id(n) = id(node_id)
RETURN n.name AS name, in_degree, out_degree, degree
ORDER 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, coefficient
MATCH (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: 0

Communities

label_propagation is fast and approximate; louvain optimises modularity.

CALL algo.louvain() YIELD node_id, community
RETURN count(DISTINCT community) AS communities
// {communities: 2}

Betweenness

Brandes betweenness centrality, exact:

CALL algo.betweenness() YIELD node_id, score
MATCH (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, hops
MATCH (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, path
RETURN 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, path
RETURN 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, embedding
RETURN 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.