Aura Graph Analytics: GraphSAGE embedding training via sessions

This Jupyter notebook is hosted here in the Neo4j Graph Data Science Client Github repository.

The notebook shows how to use the graphdatascience Python library to train an unsupervised GraphSAGE model on Cora and compute node embeddings on an Aura Graph Analytics (AGA) Session, using the typed gds.graph_sage.unsupervised endpoints.

Prerequisites

This notebook requires having the Aura Graph Analytics feature enabled for your Neo4j Aura project, and a session backed by the Python runtime.

You also need to have the graphdatascience Python library installed, version 2.1 or later.

%pip install "graphdatascience>=2.1" python-dotenv matplotlib numpy

Credentials

import os

from dotenv import load_dotenv

# This allows to load required secrets from `.env` file in local directory
load_dotenv(".env")

Aura API credentials

from graphdatascience.session import AuraAPICredentials, GdsSessions

api_credentials = AuraAPICredentials(
    client_id=os.environ["CLIENT_ID"],
    client_secret=os.environ["CLIENT_SECRET"],
    # If your account is a member of several projects, you must also specify the project ID to use
    project_id=os.environ.get("PROJECT_ID", None),
)

sessions = GdsSessions(api_credentials=api_credentials)

Creating a new session

A new session is created by calling sessions.get_or_create() with a representative name, the session memory, the cloud location, and a time-to-live (TTL), which ensures that the session is automatically deleted after being unused for the set time, to avoid incurring costs.

from datetime import timedelta

from graphdatascience.session import CloudLocation, SessionMemory

# Explicitly define the size of the session
memory = SessionMemory.m_4GB

# Specify your cloud location
cloud_location = CloudLocation("gcp", "europe-west1")

# Create a GDS session!
gds = sessions.get_or_create(
    # we give it a representative name
    session_name="graphsage-unsupervised",
    memory=memory,
    ttl=timedelta(minutes=30),
    cloud_location=cloud_location,
)

# Verify the connectivity. Hints towards TLS or firewall issues if this fails directly after get_or_create
gds.verify_connectivity()

Load Cora

The Cora citation dataset ships with the client and is loaded directly into the session, with CITES relationships treated as undirected so the random walks used by unsupervised GraphSAGE can traverse citations in both directions.

gds.graph.drop("cora", fail_if_missing=False)
gds.model.delete("gds_demo_graphsage_unsupervised", fail_if_missing=False)

G = gds.graph.datasets.load_cora(undirected=True)
print("Loaded graph:", G.name())

Train GraphSAGE (Unsupervised)

gds.graph_sage.unsupervised.train submits the training job, blocks until completion (with progress reporting), and returns the trained model together with a train summary result. featureProperties selects the node properties used as input features (here Cora’s features vector). nodeLabels and relationshipTypes default to * (project everything).

model, train_result = gds.graph_sage.unsupervised.train(
    G,
    model_name="gds_demo_graphsage_unsupervised",
    feature_properties=["features"],
    epochs=10,
    embedding_dimension=64,
    learning_rate=0.001,
    num_neighbors=[25, 10],
    activation_function="relu",
    aggregator="mean",
    num_walks=10,
    walk_depth=3,
    random_seed=42,
)

print("Trained model:", model.name())
train_result

Run Inference

gds.graph_sage.unsupervised.stream runs the predict job against the stored model and streams the results. Unsupervised GraphSAGE produces a node embedding per node (rather than class predictions). Inference projects the same featureProperties the model was trained on.

embeddings_df = gds.graph_sage.unsupervised.stream(
    G,
    model_name=model.name(),
    feature_properties=["features"],
    random_seed=42,
)

print("Columns:", list(embeddings_df.columns))
embeddings_df

Visualize embeddings

import matplotlib.pyplot as plt
import numpy as np

# colour each paper by its `subject` to see how embeddings cluster
subjects = gds.graph.node_properties.stream(G, "subject")
embeddings_df = embeddings_df.merge(subjects, on="nodeId")

# project the 64-dim embeddings to 2D with an SVD (no extra dependencies needed)
X = np.stack(embeddings_df["embedding"].to_numpy())
X = X - X.mean(axis=0)
U, _, _ = np.linalg.svd(X, full_matrices=False)
embeddings_df["x"], embeddings_df["y"] = U[:, 0], U[:, 1]

fig, ax = plt.subplots(figsize=(8, 6))
for subject in sorted(embeddings_df["subject"].unique()):
    part = embeddings_df[embeddings_df["subject"] == subject]
    ax.scatter(part["x"], part["y"], s=25, label=f"subject {subject}")
ax.set_title("GraphSAGE embeddings of Cora papers")
ax.set_xlabel("component 1")
ax.set_ylabel("component 2")
ax.legend()
fig.tight_layout()
plt.show()

Cleanup

After the analysis is done, we delete the trained model and the graph, and then delete the session. Deleting the session releases all resources associated with it, and stops incurring costs.

gds.model.delete("gds_demo_graphsage_unsupervised", fail_if_missing=False)

G.drop(fail_if_missing=False)
sessions.delete(session_name="graphsage-unsupervised")