Neo4j Aura Graph Analytics Skill

When to Use

• Running GDS algorithms in Aura Graph Analytics GDS Sessions
• Creating GdsSessions or using AuraGraphDataScience
• Remote projecting connected Neo4j data with gds.graph.project.remote(...)
• Using AuraDB Cypher API projection with { memory: ... } or { sessionId: ... }
• Processing graph data from non-Neo4j sources (Pandas, Spark, CSV)
• On-demand / pipeline workloads — ephemeral sessions, pay per session-minute
• Full isolation from the live database during analytics

When NOT to Use

• Aura Pro with embedded GDS plugin → neo4j-gds-skill
• Self-managed Neo4j with embedded GDS plugin → neo4j-gds-skill
• Writing Cypher queries → neo4j-cypher-skill
• Snowflake Graph Analytics → neo4j-snowflake-graph-analytics-skill

Deployment Decision Table

Defaults

• graphdatascience >= 2.0 required
• 2.0 endpoints: no v2 prefix — gds.page_rank.*, gds.graph.node_properties.*, gds.graph.construct(...)
• Use snake_case parameters end-to-end
• Call gds.verify_connectivity() after session creation — verifies session and, if attached, the source DB
• Estimate memory before large sessions
• Set TTL; default 1h idle, max 7d (hard 7-day lifetime cap)
• Close session when done: gds.delete() or sessions.delete(session_name=...) stops billing
• Use AuraAPICredentials.from_env() and DbmsConnectionInfo.from_env() — never hardcode credentials

Installation

pip install "graphdatascience>=2.0"     # 2.0 is the current stable release

2.0 requires: Python >= 3.10, neo4j driver 5.26–7.0, pandas 2–3, pyarrow 21–25, numpy <3.

Client 1.x (legacy)

2.0 renamed/reorganized the client. Pinned to 1.22 (graphdatascience<2)? Map:

Migration guide: Neo4j GDS Python client 2.0 migration

2.0 additions: GdsSessions.estimate(algorithms=[...]) per-algorithm memory; GdsSessions.get_or_create(show_progress=...); keyword-only GdsSessions.delete(session_name=|session_id=) returns False when nothing deleted; overwrite=True on gds.graph.project / generate / construct / filter / sample drops a same-named graph first; gds.graph.drop(...) accepts multiple graphs → list[GraphInfo];

Key Patterns

Step 1 — Authenticate

from graphdatascience.session import AuraAPICredentials, GdsSessions

sessions = GdsSessions(api_credentials=AuraAPICredentials.from_env())
# Reads: AURA_CLIENT_ID, AURA_CLIENT_SECRET, AURA_PROJECT_ID (optional)
# Create API credentials in Aura Console → Account → API credentials

If member of multiple projects: set AURA_PROJECT_ID or pass project_id=.

Step 2 — Estimate Memory

from graphdatascience.session import AlgorithmCategory, SessionMemory

# Per-algorithm + config — preferred
memory = sessions.estimate(
    node_count=1_000_000,
    relationship_count=5_000_000,
    algorithms=["wcc", "louvain", "fast_rp"],
)
# or with config:
memory = sessions.estimate(
    node_count=1_000_000,
    relationship_count=5_000_000,
    algorithms={"fast_rp": {"embedding_dimension": 128}},
)
# Coarse category estimate — 1.x style, still available
memory = sessions.estimate(
    node_count=1_000_000,
    relationship_count=5_000_000,
    algorithm_categories=[
        AlgorithmCategory.CENTRALITY,
        AlgorithmCategory.NODE_EMBEDDING,
        AlgorithmCategory.COMMUNITY_DETECTION,
    ],
)
# Returns SessionMemory tier, e.g. SessionMemory.m_8GB
# Fixed tiers: m_2GB … m_512GB — see references/limitations.md

Step 3 — Create Session

Mode A — AuraDB connected:

from graphdatascience.session import DbmsConnectionInfo, SessionMemory, CloudLocation
from datetime import timedelta

# Reads: AURA_INSTANCEID (takes precedence) or NEO4J_URI, plus NEO4J_USERNAME,
# NEO4J_PASSWORD, NEO4J_DATABASE
db_connection = DbmsConnectionInfo.from_env()
# Explicit: DbmsConnectionInfo(aura_instance_id=..., username=..., password=...)

gds = sessions.get_or_create(
    session_name="my-analysis",
    memory=memory,
    db_connection=db_connection,
    ttl=timedelta(hours=2),
)
gds.verify_connectivity()

Mode B — Self-managed Neo4j:

# Same from_env() — set NEO4J_URI (e.g. "bolt://my-server:7687"), no AURA_INSTANCEID
gds = sessions.get_or_create(
    session_name="my-analysis-sm",
    memory=SessionMemory.m_8GB,
    db_connection=DbmsConnectionInfo.from_env(),
    ttl=timedelta(hours=2),
    cloud_location=CloudLocation("gcp", "europe-west1"),
)
gds.verify_connectivity()

Mode C — Standalone (no Neo4j DB):

gds = sessions.get_or_create(
    session_name="my-standalone",
    memory=SessionMemory.m_4GB,
    ttl=timedelta(hours=1),
    cloud_location=CloudLocation("gcp", "europe-west1"),
)
gds.verify_connectivity()

get_or_create() is idempotent; reconnects to existing session by name.

Step 4 — Project Graph

From connected Neo4j (remote projection):

query = """
    CALL () {
        MATCH (p:Person)
        OPTIONAL MATCH (p)-[r:KNOWS]->(p2:Person)
        RETURN p AS source, r AS rel, p2 AS target,
               p {.age, .score} AS sourceNodeProperties,
               p2 {.age, .score} AS targetNodeProperties
    }
    RETURN gds.graph.project.remote(source, target, {
        sourceNodeLabels:     labels(source),
        targetNodeLabels:     labels(target),
        sourceNodeProperties: sourceNodeProperties,
        targetNodeProperties: targetNodeProperties,
        relationshipType:     type(rel)
    })
"""

G, result = gds.graph.project.cypher(
    graph_name="my-graph",
    query=query,
    undirected_relationship_types=["KNOWS"],
)
print(f"Projected {G.node_count()} nodes, {G.relationship_count()} relationships")

CALL () { ... } required for multi-pattern MATCH. Use UNION inside CALL for multiple labels/rel types. Remote query must use gds.graph.project.remote(...); graph name goes to gds.graph.project.cypher(...), not the query. Query containing gds.graph.project without .remote is auto-rewritten with a warning. undirectedRelationshipTypes / inverseIndexedRelationshipTypes inside the query → ValueError — pass as method args.