Neo4j Aura Graph Analytics Skill

# neo4j-aura-graph-analytics-skill

Guides agents through **Aura Graph Analytics (AGA)** — Neo4j's serverless, on-demand GDS compute environment. Algorithms run in isolated ephemeral sessions billed per minute; no embedded GDS plugin required.

## What this skill covers

- Authentication with Aura API credentials (`GdsSessions`, `AuraAPICredentials.from_env()`)
- Memory estimation and `SessionMemory` tier selection
- Session creation, reconnection, listing, and deletion (`get_or_create`, TTL)
- Three data source modes: AuraDB-connected, self-managed Neo4j, standalone (Pandas/Spark)
- Remote graph projection (`gds.v2.graph.project(..., query)` with `gds.graph.project.remote()`)
- Python client v2 endpoint shape (`gds.v2.*`) without mixing camelCase/snake_case; v1 fallback when needed
- AuraDB Cypher API projection with `memory` or `sessionId`
- Standalone graph construction from DataFrames (`gds.v2.graph.construct()`)
- Algorithm execution: mutate / stream / write modes
- Async job polling pattern
- Result retrieval (`gds.v2.graph.node_properties.stream()`, `db_node_properties`)
- Write-back to connected Neo4j; cleanup before session deletion
- Common errors and mitigations (session expired, graph not projected, memory exceeded)

## Compatibility

`graphdatascience >= 1.15` · Aura Business Critical and VDC tiers · Python >= 3.8

## Not covered

- **Embedded GDS plugin** (Aura Pro, self-managed Neo4j) → `neo4j-gds-skill`
- **Cypher query authoring** → `neo4j-cypher-skill`
- **Snowflake Graph Analytics** → `neo4j-snowflake-graph-analytics-skill`

## Install

```bash
npx skills add https://github.com/neo4j-contrib/neo4j-skills --skill neo4j-aura-graph-analytics-skill
```


# AGA vs Embedded GDS — Feature Comparison

| Feature | AGA (serverless) | GDS plugin (embedded) |
|---|---|---|
| Topological link prediction | ❌ Not supported | ✅ |
| ML model persistence across sessions | ❌ Session-local only | ✅ Persistent in model catalog |
| Cypher API (`CALL gds.*`) | ✅ AuraDB attached sessions only; limited vs plugin | ✅ |
| Non-Neo4j data sources | ✅ Pandas, Spark, Arrow | ❌ |
| Aura BC / VDC | ✅ | ❌ |
| Aura Pro | ❌ | ✅ |
| Billing | Per session-minute | Included in AuraDB |
| DB performance isolation | ✅ Full isolation | ❌ Shares DB resources |

## SessionMemory Tiers

`m_2GB`, `m_4GB`, `m_8GB`, `m_16GB`, `m_24GB`, `m_32GB`, `m_48GB`, `m_64GB`, `m_128GB`, `m_192GB`, `m_256GB`

## AlgorithmCategory Values

`CENTRALITY`, `COMMUNITY_DETECTION`, `SIMILARITY`, `PATH_FINDING`, `NODE_EMBEDDING`

## Available Cloud Locations

```python
print(sessions.available_cloud_locations())
```

Common: `CloudLocation("gcp", "europe-west1")`, `CloudLocation("gcp", "us-east1")`, `CloudLocation("aws", "us-east-1")`


# AGA Full Workflow Examples

## AuraDB — PageRank + FastRP → Write Back

```python
from graphdatascience.session import (
    AuraAPICredentials, GdsSessions, DbmsConnectionInfo,
    SessionMemory, AlgorithmCategory
)
from datetime import timedelta
import os

# 1. Auth
sessions = GdsSessions(api_credentials=AuraAPICredentials.from_env())

# 2. Size
memory = sessions.estimate(
    node_count=500_000,
    relationship_count=2_000_000,
    algorithm_categories=[AlgorithmCategory.CENTRALITY, AlgorithmCategory.NODE_EMBEDDING],
)

# 3. Session
gds = sessions.get_or_create(
    session_name="prod-analysis",
    memory=memory,
    db_connection=DbmsConnectionInfo.from_env(),
    ttl=timedelta(hours=4),
)
gds.v2.verify_session_connectivity()
gds.v2.verify_db_connectivity()

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