Projecting a Graph for GDS

Projecting a Graph for GDS

GDS runs on an in-memory projection — pick the nodes, edges, properties you actually need.

Why it matters

Projections turn a Neo4j graph into a memory-resident structure suited to PageRank, Louvain, BFS — smaller is faster.

Going deeper

GDS algorithms run on an in-memory projection, not the stored graph, because the disk graph is optimized for transactional traversal, while algorithms need a compact array-based structure:

CALL gds.graph.project(
  'rankGraph',
  'Page',
  {LINKS: {orientation: 'NATURAL'}}
);
CALL gds.pageRank.write('rankGraph', {writeProperty:'rank'});

Three projection decisions control cost and correctness:

1. Scope — project only the labels/relationship types the algorithm needs; smaller graph, less memory, faster run.
2. Orientation — NATURAL, REVERSE, or UNDIRECTED changes the meaning of the result (PageRank on reversed edges answers a different question).
3. Properties — only project the relationship weights/node properties the algorithm actually consumes.

Budget the memory with gds.graph.project.estimate before projecting a huge graph; an over-broad projection is the most common GDS out-of-memory cause.

A GDS projection is photocopying just the pages you need before marking them up. You don't scribble analysis all over the master archive (the live OLTP graph) — you copy the relevant nodes and edges into a fast scratch space, run PageRank/Louvain there, then write back only the conclusions. Copy the whole archive and you've wasted memory; copy too little and the analysis is wrong.

• Projecting the whole graph. Wastes memory, risks OOM. Fix: scope to needed labels/types; estimate first.
• Wrong orientation. Silently answers a different question. Fix: match orientation to the algorithm's intent.
• Stale projection. Reusing an old projection after writes gives outdated results. Fix: re-project or use a projection lifecycle.