Neo4j Gds Skill

When to Use

• Running GDS algorithms against embedded GDS plugin through Python client (graphdatascience)
• Running GDS algorithms through CALL gds.* Cypher procedures
• Aura Pro, self-managed Neo4j, local Neo4j, or offline DBMS with GDS plugin installed
• Projecting named in-memory graphs, running centrality/community/similarity/path/embedding algorithms
• Chaining algorithms via mutate mode; building FastRP → KNN pipelines
• Writing node embeddings for Neo4j vector indexes / structural similarity search
• Memory estimation before large graph operations

When NOT to Use

• Aura Graph Analytics Sessions / AGA / `GdsSessions` / `AuraGraphDataScience` → neo4j-aura-graph-analytics-skill
• AuraDB Cypher API with `{ memory: ... }` or `{ sessionId: ... }` → neo4j-aura-graph-analytics-skill
• Cypher query authoring → neo4j-cypher-skill
• Driver/connection setup → neo4j-driver-python-skill
• GraphRAG retrieval → neo4j-graphrag-skill
• Creating/querying vector indexes over written embeddings → neo4j-vector-index-skill

Pre-flight

Use only with embedded GDS plugin.

from graphdatascience import GraphDataScience

gds = GraphDataScience("neo4j+s://xxx.databases.neo4j.io", auth=("neo4j", "pw"))   # AuraDS; aura_ds auto-derived
gds = GraphDataScience("bolt://localhost:7687", auth=("neo4j", "password"))
print(gds.server_version())

RETURN gds.version() AS gds_version

GDS plugin unavailable: client raises GdsNotFound at construction; Cypher raises Unknown function 'gds.version'. AuraDB serverless analytics → neo4j-aura-graph-analytics-skill. Self-managed/local → install or enable GDS plugin.

pip install graphdatascience                 # Python client 2.0+
pip install "graphdatascience[rust-ext]"     # optional: faster serialization

Compatibility: graphdatascience 2.0 — GDS >= 2.13 and < 2.28 / < 2026.9, Python >= 3.10 and < 3.15, Neo4j Python driver >= 5.26 and < 7.0, pandas 2–3, pyarrow 21–25. GDS server < 2.13 → DeprecationWarning at construction; pin graphdatascience<2 (client 1.22) there.

Client 1.x fallback (GDS server < 2.13)

Migration guide: Neo4j GDS Python client 2.0 migration

GDS plugin releases track the server: 2026.08.1 requires Neo4j 2026.08 — check the GDS compatibility table before upgrading either side.

GDS plugin 2026.07.0 removed CALL gds.userLog() — read hints and warnings from driver result summary notifications or the Neo4j debug log; track task progress with CALL gds.listProgress().

2.0 client rules:

• Plain endpoints, no v2 prefix — untyped 1.x endpoints and gds.v2.* are gone
• snake_case parameters: page_rank, fast_rp, mutate_property, write_property
• Typed result attributes: result.write_millis, not result["writeMillis"] (stream still returns DataFrame)
• Server version via gds.server_version() — no gds.version() client method (Cypher RETURN gds.version() still valid)
• Procedure aliases: gds.betweenness ≡ gds.betweenness_centrality; also gds.closeness, gds.degree, gds.eigenvector, gds.harmonic, gds.kcore
• Pipelines: gds.pipeline.node_classification / link_prediction / node_regression — the only API in 2.0
• No async/job-handle API on the plugin surface — compute(), *_async, gds.jobs are AGA Sessions only

Graph Catalog Operations

Native Projection

CALL gds.graph.project(
  'myGraph',
  ['Person', 'City'],
  { KNOWS: { orientation: 'UNDIRECTED' }, LIVES_IN: {} }
)
YIELD graphName, nodeCount, relationshipCount

G, result = gds.graph.project.native("myGraph", "Person", "KNOWS")
print(result.node_count, result.relationship_count)

G, result = gds.graph.project.native(
    "myGraph",
    {"Person": {"properties": ["age", "score"]}, "City": {}},
    {"KNOWS": {"orientation": "UNDIRECTED"}, "LIVES_IN": {"properties": ["since"]}},
    overwrite=True,   # drop same-named graph first
)

Native projection: plugin/simple Python-client workflow only. AGA Sessions → neo4j-aura-graph-analytics-skill. 1.x fallback: gds.v2.graph.project(...).

Cypher Projection (use for new Cypher workflows, filters, transforms)

G, result = gds.graph.project.cypher(
    """
    MATCH (source:Person)-[r:KNOWS]->(target:Person)
    WHERE source.active = true
    RETURN gds.graph.project($graph_name, source, target,
        { sourceNodeProperties: source { .score }, relationshipType: 'KNOWS' })
    """,
    graph_name="activeGraph",
)

gds.graph.project.cypher(query) takes no database= — set GraphDataScience(..., database=...) at construction or call gds.set_database(...) before projecting. Query must end with exactly one RETURN gds.graph.project(...). If validation fails: use gds.run_cypher(...), then gds.graph.get("graphName"). 1.x fallback: gds.graph.cypher.project(query, database=...).

AGA Sessions → neo4j-aura-graph-analytics-skill; never use plugin Cypher projection.

Undirected Projection

Native projection: set orientation: 'UNDIRECTED' per relationship type. Plugin Cypher projection: set undirectedRelationshipTypes: ['*'] in fifth gds.graph.project(...) config argument.

Leiden is defined for directed and undirected graphs. Project undirected relationships when community structure is naturally symmetric.

Inspect and Drop

G.node_count()              # 12_043
G.relationship_count()      # 87_211
G.node_properties()         # projected + mutated properties by label
G.relationship_properties() # projected + mutated properties by type
G.size_in_bytes()
gds.graph.drop(G)           # frees JVM heap; returns list[GraphInfo]

G = gds.graph.get("myGraph")       # re-attach to existing projection

gds.graph.list()

Memory Estimation — run before large projections and algorithms

CALL gds.graph.project.estimate(['Person'], 'KNOWS')
YIELD requiredMemory, bytesMin, bytesMax, nodeCount, relationshipCount

est = gds.graph.project.estimate(node_projection=["Person"], relationship_projection=["KNOWS"])
print(est.required_memory)

G, project_result = gds.graph.project.native("myGraph", "Person", "KNOWS")
print(project_result.node_count)

# Algorithm estimation:
est = gds.page_rank.estimate(G, damping_factor=0.85)
print(est.required_memory)

Execution Modes

Pattern: stream to verify → mutate to chain → write to persist.