neo4j-aura-graph-analytics-skill

使用する場合

• Aura Graph Analytics GDS セッションで GDS アルゴリズムを実行する場合
• GdsSessions を作成する場合、または AuraGraphDataScience を使用する場合
• gds.graph.project.remote(...) を使って、接続された Neo4j データをリモートでプロジェクションする場合
• { memory: ... } または { sessionId: ... } を使って AuraDB Cypher API のプロジェクションを行う場合
• Neo4j 以外のソース（Pandas、Spark、CSV）のグラフデータを処理する場合
• オンデマンド／パイプラインのワークロード — 一時的なセッションを使用し、セッション分単位で課金されます
• 分析中にライブデータベースから完全に分離する場合

使用しない場合

• 埋め込み GDS プラグインを使用する Aura Pro → neo4j-gds-skill
• 埋め込み GDS プラグインを使用するセルフマネージド Neo4j → neo4j-gds-skill
• Cypher クエリを記述する場合 → neo4j-cypher-skill
• Snowflake Graph Analytics → neo4j-snowflake-graph-analytics-skill

---

デプロイメントの選択表

デプロイメント	使用するもの
AuraDB Free	このスキル — 最大 m_2GB、同時セッション数 1、課金なし
Graph Analytics プラグインを有効にした Aura Pro（軽量な探索、共有リソース）	neo4j-gds-skill
Aura Pro／Pro Trial ＋ セッション（分離されたコンピューティング）	このスキル — 最大 128 GB（Pro）／8 GB（Pro Trial）、同時セッション数 100／3
AuraDB ＋ Python クライアントセッション	このスキル
AuraDB ＋ Cypher API	AGA 固有のプロジェクション／セッションに関する注意事項にはこのスキル、クエリの作成には neo4j-cypher-skill
セルフマネージド Neo4j ＋ AGA セッション	このスキル
セルフマネージド Neo4j ＋ 埋め込みプラグイン	neo4j-gds-skill
Neo4j 以外のデータ（Pandas、Spark）	このスキル（スタンドアロンモード）

---

デフォルト

• graphdatascience >= 2.0 が必要です。>= 2.2 を推奨します
• 2.0 エンドポイント：v2 プレフィックスはありません — gds.page_rank.*、gds.graph.node_properties.*、gds.graph.construct(...)
• 最初から最後まで snake_case パラメーターを使用します
• セッション作成後に gds.verify_connectivity() を呼び出します — セッションと、接続されている場合はソース DB を検証します
• 大規模なセッションの前にメモリを見積もります
• TTL を設定します。デフォルトはアイドル時 1h、最大 7d（7 日間のハード上限）
• 完了したらセッションを閉じます：gds.delete() または sessions.delete(session_name=...) を実行すると課金が停止します
• AuraAPICredentials.from_env() と DbmsConnectionInfo.from_env() を使用し、認証情報をハードコードしないでください

---

インストール

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

2.0～2.2 に必要な要件：Python >= 3.10、neo4j ドライバー 5.26～7.0、pandas 2～3、pyarrow 21～25、numpy <3。

クライアント 1.x（レガシー）

2.0 ではクライアントの名前と構成が変更されました。1.22 に固定する場合（graphdatascience<2）は、次のように対応します。

1.x	2.0
gds.v2.<endpoint>	gds.<endpoint> — v2 プレフィックスがなくなり、型指定のない 1.x エンドポイントは削除されました
gds.graph.project(graph_name, query)（リモート）	gds.graph.project.cypher(graph_name, query)
gds.graph.project_native(...)	gds.graph.project.native(...)
GraphV2 / ModelV2	Graph / Model — from graphdatascience import Graph
Graph.drop(failIfMissing=) / Model.drop(failIfMissing=)	fail_if_missing=
gds.v2.verify_session_connectivity() / gds.v2.verify_db_connectivity()	gds.verify_connectivity() — 1.x にも存在しましたが、v2 名前空間はなくなりました
run_cypher(..., retryable=)	削除 — 常に再試行します
gds.graph.project.cypher(database=...)	削除 — 投影の前に gds.set_database(...) を実行します
gds.graph.node_labels.mutate(write_concurrency=, job_id=)	パラメーターは削除されました
ArrowEndpointVersion.from_arrow_info	check_version_compatibility

移行ガイド：Neo4j GDS Python client 2.0 migration

2.0 での追加機能：GdsSessions.estimate(algorithms=[...]) でアルゴリズムごとのメモリを推定、GdsSessions.get_or_create(show_progress=...)、キーワード専用の GdsSessions.delete(session_name=|session_id=) は削除対象がない場合に False を返します。gds.graph.project / generate / construct / filter / sample の overwrite=True は、同名のグラフを先に削除します。gds.graph.drop(...) は複数のグラフを受け付け、list[GraphInfo] を返します。

2.1 での追加機能：CALL { … } IN TRANSACTIONS に対応する gds.run_cypher(query, auto_commit=True)（2.0 のデフォルトでは、再試行可能なトランザクションで実行すると拒否されます）。gds.db_driver() はセッションクライアントが管理する neo4j.Driver を返します（gds.close() で閉じられます）。QueryMode では mode="READ" / "WRITE" の文字列も受け付けます。

---

主なパターン

ステップ 1 — 認証

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

複数のプロジェクトまたは組織に所属している場合は、AURA_PROJECT_ID を設定するか、project_id= を渡してください。デフォルトのプロジェクトを決定する際、2.1 では組織が先に確認されます。

ステップ 2 — メモリの推定

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

ステップ 3 — セッションの作成

モード A — AuraDB に接続：

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()

モード B — セルフマネージド 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()

モード C — スタンドアロン（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() は冪等です。同じ名前の既存セッションに再接続します。

ステップ 4 — プロジェクトグラフ

接続済みの Neo4j から（リモートプロジェクション）：

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")

複数のパターンを MATCH するには、CALL () { ... } が必要です。複数のラベル／リレーションシップタイプを指定する場合は、CALL 内で UNION を使用します。 リモートクエリでは gds.graph.project.remote(...) を使用する必要があります。グラフ名はクエリではなく、gds.graph.project.cypher(...) に渡します。.remote を付けずに gds.graph.project を含むクエリは、警告とともに自動的に書き換えられます。クエリ内に undirectedRelationshipTypes／inverseIndexedRelationshipTypes を指定すると ValueError が発生します。メソッドの引数として渡してください。 セッションにプロジェクトできるのは数値のノードプロパティのみです。ストリーミング時に文字列プロパティを取得するには、db_node_properties を使用してください。 スタンドアロンセッションではリモートプロジェクションを実行できません。ValueError: Remote projection is only supported for attached Sessions. が発生します。 1.x の代替方法：gds.graph.project(graph_name=..., query=...)。

ネイティブリモートプロジェクション（Cypher クエリなし） — gds.graph.project.native(...) は、ラベル／タイプのフィルターを使って、アタッチ済みの DB からプロジェクションを作成します。

G, result = gds.graph.project.native(
    "my-graph",
    ["Person"],                              # node_label_filter
    ["KNOWS"],                               # relationship_type_filter
    node_properties=["age", "score"],
    undirected_relationship_types=["KNOWS"],
)

アタッチ済みのセッションでのみ使用できます。ラベル／タイプでフィルターするプロジェクションには project.native を、変換、計算プロパティ、または異なるパターンをまとめる UNION が必要な場合は project.cypher を使用してください。

AuraDB Cypher API プロジェクション：

CYPHER runtime=parallel
MATCH (source)
OPTIONAL MATCH (source)-->(target)
RETURN gds.graph.project(
  'my-graph',
  source,
  target,
  {},
  { memory: '2GB' }
)

既存の明示的なセッション：

CYPHER runtime=parallel
MATCH (source)
OPTIONAL MATCH (source)-->(target)
RETURN gds.graph.project(
  'my-graph',
  source,
  target,
  {},
  { sessionId: '00000000-11111111' }
)

Cypher API では gds.graph.project(...) を使用し、gds.graph.project.remote(...) は使用しません。memory、ttl、sessionId、batchSize は、5 番目の設定引数に指定してください。

Cypher API によるセッション管理：

CALL gds.session.getOrCreate('test-session', '2GB', duration({minutes: 30}))
YIELD id, name, status
RETURN id, name, status

CALL gds.session.list()
YIELD id, name, status, memory
RETURN id, name, status, memory

Cypher API の暗黙的なセッションは、そのセッション内のプロジェクショングラフをすべて削除すると削除されます。

Pandas DataFrame から（スタンドアロンモード）：

import pandas as pd

nodes_df = pd.DataFrame([
    {"nodeId": 0, "labels": "Person", "age": 30},
    {"nodeId": 1, "labels": "Person", "age": 25},
])
rels_df = pd.DataFrame([
    {"sourceNodeId": 0, "targetNodeId": 1, "relationshipType": "KNOWS"},
])

G = gds.graph.construct("my-graph", [nodes_df], [rels_df])

必須列 — ノード：nodeId（int）、labels（str）。リレーションシップ：sourceNodeId、targetNodeId、relationshipType。construct() の実行前に文字列のノードプロパティを削除してください。セッションで受け付けられるプロパティは数値のみです。

ステップ 5 — アルゴリズムを実行する

# Mutate — chain results without writing to DB
gds.page_rank.mutate(G, mutate_property="pagerank", damping_factor=0.85)
gds.fast_rp.mutate(G,
    mutate_property="embedding",
    embedding_dimension=128,
    feature_properties=["pagerank"],
    random_seed=42,
)

# Stream — inspect results as DataFrame
df = gds.page_rank.stream(G)
print(df.sort_values("score", ascending=False).head(10))

# Write — persist to connected Neo4j DB (connected modes only)
gds.louvain.write(G, write_property="community")

ML パイプライン：gds.pipeline.node_classification／link_prediction／node_regression — 2.0 で使用できる唯一の API です。 1.x の代替方法：gds.v2.page_rank.mutate(...)。gds.pageRank.mutate(...) のような、型指定のない 1.x のエンドポイントは 2.0 では使用できません。 プラグインアルゴリズムのリファレンス → neo4j-gds-skill。AGA の制限は異なります。

ステップ 6 — 非同期ジョブのポーリング

時間のかかるアルゴリズム — ノンブロッキングの compute() は JobHandle を返します。

import time

job = gds.page_rank.compute(G, damping_factor=0.85)   # algorithm config only — no mutate/write args
while not job.done():
    time.sleep(5)
    print(f"Job status: {job.status().status} {job.status().progress_percent()}")
if not job.status().succeeded():                       # status string "done" / "aborted" / "running"
    raise RuntimeError(f"Algorithm job failed: {job.status().status}")
df = job.stream(wait=False)                            # raises JobNotFinishedError if not done
# or: job.mutate(mutate_property="pagerank")  /  job.write(write_properties="pagerank") → WriteJobHandle

ハンドルのメソッド：.job_id()、.status() → JobStatus（.status、.progress、.succeeded()、.aborted()、.running()）、.done()、.wait(*, termination_flag=None)、.cancel()、.summary(wait=True)、.stream(wait=True)、.mutate(mutate_property=..., wait=True)、.write(write_properties=...)。

GraphSAGE の予測をジョブとして実行 [2.2]：gds.graph_sage.compute(G, model_name)（クラシックモデル）、gds.graph_sage.supervised.compute(G, model_name, feature_properties)（predicted_class、predicted_probabilities を追加）、gds.graph_sage.unsupervised.compute(G, model_name, feature_properties) — いずれも JobHandle を返します。.stream()／.mutate()／.write() で実体化します。 非同期プロジェクションは ProjectionJobHandle（gds.graph.project.native_async(...)、cypher_async(...)）を返します。書き戻しでは WriteJobHandle が生成されます。ジョブの一覧表示／復元：

gds.jobs.list()                     # JobInfo per job: job_id, name
handle = gds.jobs.get(G, job_id)    # concrete handle type for the job

ステップ 7 — 結果を取得する

# Stream node properties
result_df = gds.graph.node_properties.stream(
    G,
    node_properties=["pagerank", "embedding"],
    db_node_properties=["name"],   # connected modes only — fetches string props from DB
)
result_df.head(10)

スタンドアロンモードでは db_node_properties は使用できません。ソース DataFrame と結合してください：

result_df = gds.graph.node_properties.stream(G, ["pagerank"])
result_df.merge(nodes_df[["nodeId", "name"]], how="left")

ステップ 8 — 書き戻しとクリーンアップ

# Write node properties to connected Neo4j
gds.graph.node_properties.write(G, ["pagerank", "embedding"])

# Write relationship properties
gds.graph.relationships.write(G, "SIMILAR", ["score"])

# Query connected DB from session
gds.run_cypher("MATCH (n:Person) RETURN count(n)")

# Drop projected graph
gds.graph.drop(G)

# Delete session
sessions.delete(session_name="my-analysis")
# or: gds.delete()

削除する前に書き戻してください。書き込まれていない結果は、セッションを閉じると失われます。

セッション管理

# List active sessions
from pandas import DataFrame
DataFrame(sessions.list())

# Reconnect to existing session
gds = sessions.get_or_create(session_name="my-analysis", memory=..., db_connection=...)

---

よくあるエラー

エラー	原因	修正方法
AuthenticationError / 401	CLIENT_ID／CLIENT_SECRET が間違っています	Aura Console → Account → API credentials で再生成します
期限切れのセッションを取得した際の RuntimeError	TTL を超過しています	sessions.list() で確認し、セッションを再作成します
SessionNotFoundError	セッションの期限切れ（TTL 超過）または名前の入力ミスです	sessions.list() で確認し、セッションを再作成します
GraphNotFoundError	プロジェクションが削除されたか、再プロジェクションせずにセッションが再接続されました	gds.graph.project.cypher() または gds.graph.construct() を再実行します
ValueError: Remote projection is only supported for attached Sessions.	スタンドアロンセッションではリモートプロジェクションを実行できません	代わりに DataFrame から gds.graph.construct(...) を使用します
NotAvailableInStandaloneSessions	この機能には DB のアタッチが必要です（例：gds.topological_link_prediction、リモートプロジェクション）	DB をアタッチするか、別のアルゴリズムを選択します
アルゴリズムジョブが FAILED	メモリ上限を超えたか、サポート対象外のアルゴリズムです	SessionMemory を増やします。アタッチ済みセッションのみで使える機能については NotAvailableOutsideAura を確認します
MemoryEstimationExceeded	グラフが推定より大きいです	実際の件数で再推定し、次に上のティアを選択します
セッション再接続後に結果が空になる	セッションを閉じる前に結果が書き込まれていません	常に gds.delete() の前に書き込みまたはストリーミングを行います
String node properties not supported	nodes DataFrame に文字列列があります	gds.graph.construct() の前に文字列列を削除し、後で db_node_properties を使用して文字列を取得します
AGA not enabled for project	AGA 機能が有効化されていません	Aura Console → project settings で有効にします

---

参考資料

必要に応じて読み込んでください：

• references/workflows.md — AuraDB とスタンドアロンのワークフローの詳細な例、Spark 統合
• references/limitations.md — AGA と組み込み GDS の機能比較表、SessionMemory のティア、クラウドのロケーション

WebFetch

必要な情報	URL
AGA Python クライアントのドキュメント	https://neo4j.com/docs/graph-data-science-client/current/aura-graph-analytics/
AGA Cypher API のドキュメント	https://neo4j.com/docs/graph-data-science/current/aura-graph-analytics/cypher/
クライアントの移行ガイド 1.x → 2.0	https://neo4j.com/docs/graph-data-science-client/current/migration-from-1x/
AuraDB チュートリアルノートブック	https://github.com/neo4j/graph-data-science-client/blob/main/examples/graph-analytics-serverless.ipynb
GDS アルゴリズムのリファレンス	https://neo4j.com/docs/graph-data-science/current/algorithms/

---

チェックリスト

• Aura API 認証情報を作成し、環境変数（AURA_CLIENT_ID、AURA_CLIENT_SECRET）に設定した
• 接続済みセッションの場合は、DbmsConnectionInfo.from_env() 用に AURA_INSTANCEID または NEO4J_URI、および NEO4J_USERNAME、NEO4J_PASSWORD を設定した
• Aura プロジェクトで AGA 機能を有効にした（Aura Console → project settings）
• セッション作成前にメモリを推定した（sessions.estimate(..., algorithms=[...])）
• データソースに近いクラウドロケーションを選択した
• セッション作成後に gds.verify_connectivity() を呼び出した
• リモートプロジェクションでは、クエリ内で gds.graph.project.remote(...) を使用する gds.graph.project.cypher(graph_name, query) を使用した
• リモートプロジェクションのグラフ名を、リモート関数ではなくエンドポイントに渡した
• undirected_relationship_types はクエリ内ではなく、メソッドの引数として渡した
• AuraDB Cypher API のプロジェクションでは、5 番目の設定マップを memory または sessionId に使用した
• 明示的な Cypher API セッションでは gds.session.getOrCreate(...) を使用し、暗黙的なセッションはプロジェクション済みグラフとともに削除した
• アイドル状態のセッションで予期しないコストが発生しないよう、TTL を設定した
• 結果を読み取る前に、非同期アルゴリズムジョブが RUNNING_DONE になるまでポーリングした
• 削除前に、結果を書き戻した（接続モード）か、ストリーミングして永続化した（スタンドアロン）
• 完了後にセッションを削除した（sessions.delete(session_name=...) または gds.delete()）