neo4j-gds-skill

适用场景

• 通过 Python 客户端（graphdatascience）对内嵌式 GDS 插件运行 GDS 算法
• 通过 CALL gds.* Cypher 过程运行 GDS 算法
• 安装了 GDS 插件的 Aura Pro、自托管 Neo4j、本地 Neo4j 或离线 DBMS
• 投影命名的内存图，运行中心性、社区、相似度、路径和嵌入算法
• 通过 mutate 模式串联算法；构建 FastRP → KNN 工作流
• 写入节点嵌入，以用于 Neo4j 向量索引／结构相似度搜索
• 在大型图操作前估算内存

不适用场景

• Aura Graph Analytics Sessions / AGA / GdsSessions / AuraGraphDataScience → neo4j-aura-graph-analytics-skill
• 带有 { memory: ... } 或 { sessionId: ... } 的 AuraDB Cypher API → neo4j-aura-graph-analytics-skill
• 编写 Cypher 查询 → neo4j-cypher-skill
• 驱动程序／连接设置 → neo4j-driver-python-skill
• GraphRAG 检索 → neo4j-graphrag-skill
• 创建／查询基于已写入嵌入的向量索引 → neo4j-vector-index-skill

场景	使用
配备 GDS 插件的 Aura Pro	本技能
配备 GDS 插件的自托管／本地／离线 Neo4j	本技能
AuraDB 无服务器分析会话	neo4j-aura-graph-analytics-skill
连接到 AGA 会话的自托管 Neo4j	neo4j-aura-graph-analytics-skill
非 Neo4j 数据源	neo4j-aura-graph-analytics-skill

---

预检

仅适用于内嵌式 GDS 插件。

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 插件不可用：客户端在构造时会引发 GdsNotFound；Cypher 会引发 Unknown function 'gds.version'。AuraDB 无服务器分析 → neo4j-aura-graph-analytics-skill。自托管／本地环境 → 安装或启用 GDS 插件。

pip install "graphdatascience>=2.1"          # 2.1 required for GDS 2026.09
pip install "graphdatascience[rust-ext]"     # optional: faster serialization

兼容性：graphdatascience 2.1 / 2.2 — GDS >= 2.13 且 < 2.28 / < 2026.10；2.0 — GDS < 2026.9。所有版本：Python >= 3.10 且 < 3.15，Neo4j Python 驱动程序 >= 5.26 且 < 7.0，pandas 2–3，pyarrow 21–25。GDS 服务 < 2.13 → 构造时发出 DeprecationWarning；此类环境请固定为 graphdatascience<2（客户端 1.22）。

1.x 客户端回退（GDS 服务 < 2.13）

2.0	1.x 客户端
gds.page_rank、gds.louvain、… — 无 v2 前缀	gds.v2.page_rank、gds.v2.louvain、…
gds.graph.project.native(...)	gds.v2.graph.project(...)
gds.graph.project.cypher(query)	gds.graph.cypher.project(query, database=...)
Graph / Model	GraphV2 / ModelV2
gds.graph.drop(...) → list[GraphInfo]	gds.v2.graph.drop(...) → 单个 GraphInfo
Graph.drop(fail_if_missing=)	Graph.drop(failIfMissing=)
run_cypher(...) — 始终重试	run_cypher(..., retryable=...)

迁移指南：Neo4j GDS Python 客户端 2.0 迁移

GDS 插件版本与服务版本同步发布：2026.09.0 要求 Neo4j 2026.09 — 升级任一端之前，请查看 GDS 兼容性表。

GDS 插件 2026.07.0 移除了 CALL gds.userLog() — 请从驱动程序结果摘要通知或 Neo4j 调试日志中读取提示和警告；使用 CALL gds.listProgress() 跟踪任务进度。

2.0 客户端规则：

• 使用普通端点，不带 v2 前缀 — 无类型的 1.x 端点和 gds.v2.* 均已移除
• 参数使用 snake_case：page_rank、fast_rp、mutate_property、write_property
• 结果属性带类型：使用 result.write_millis，而非 result["writeMillis"]（stream 仍返回 DataFrame）
• 通过 gds.server_version() 获取服务版本 — 客户端没有 gds.version() 方法（Cypher RETURN gds.version() 仍有效）
• 过程别名：gds.betweenness ≡ gds.betweenness_centrality；另有 gds.closeness、gds.degree、gds.eigenvector、gds.harmonic、gds.kcore
• 管道：gds.pipeline.node_classification / link_prediction / node_regression — 这是 2.0 中唯一的 API
• gds.run_cypher(query, auto_commit=True) [2.1] 用于 CALL { … } IN TRANSACTIONS — 2.0 默认的可重试事务不支持此语法；在 2.0 中请直接使用 Neo4j 驱动程序
• gds.db_driver() [2.1] → 底层的 neo4j.Driver，用于自定义会话/事务；仅当客户端创建了它时，gds.close() 才会将其关闭
• 凡是可接受 QueryMode 的地方，也接受 mode="READ" / "WRITE" 字符串 [2.1]
• 插件接口中没有异步/任务句柄 API — compute()、*_async、gds.jobs 仅适用于 AGA Sessions

---

图目录操作

原生投影

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
)

原生投影：仅适用于插件/简单 Python 客户端工作流。AGA Sessions → neo4j-aura-graph-analytics-skill。 1.x 回退：gds.v2.graph.project(...)。

Cypher 投影（用于新的 Cypher 工作流、筛选和转换）

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) 不接受 database= — 请在构造时设置 GraphDataScience(..., database=...)，或在投影前调用 gds.set_database(...)。 查询必须以且仅以一个 RETURN gds.graph.project(...) 结尾。如果验证失败：请使用 gds.run_cypher(...)，然后调用 gds.graph.get("graphName")。 1.x 回退：gds.graph.cypher.project(query, database=...)。

AGA Sessions → neo4j-aura-graph-analytics-skill；切勿使用插件 Cypher 投影。

无向投影

原生投影：为每种关系类型设置 orientation: 'UNDIRECTED'。 插件 Cypher 投影：在 gds.graph.project(...) 的第五个配置参数中设置 undirectedRelationshipTypes: ['*']。

Leiden 适用于有向图和无向图。如果社区结构天然对称，请投影无向关系。

检查和删除

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

内存估算 — 大型投影和算法运行前执行

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)

---

执行模式

模式	副作用	返回内容	适用场景
stream	无	每个节点／节点对一行	检查结果；取前 N 项
stats	无	单行聚合结果	汇总／收敛性检查
mutate	仅向内存图添加节点属性或关系类型／属性	统计行	链式运行算法
write	将节点属性或关系持久化到 Neo4j DB	统计行	最后一步——使其可查询

模式：先用 stream 验证 → 再用 mutate 链式运行 → 最后用 write 持久化。

mutate_property 不得存在于内存图中。KNN 等关系算法还需要 mutate_relationship_type。 write 之后，请重新投影，以便在后续 GDS 调用中使用已写入的属性（内存图看不到写入 DB 的数据）。

---

gds.util.asNode() — 丰富 Stream 结果

stream 模式会返回 nodeId（GDS 内部整数）。gds.util.asNode(nodeId) 会将其转换回 DB 节点，以便访问其属性。

// Single property
CALL gds.pageRank.stream('myGraph', {})
YIELD nodeId, score
RETURN gds.util.asNode(nodeId).name AS name, score
ORDER BY score DESC LIMIT 10

// Multiple properties — convert once with WITH
CALL gds.pageRank.stream('myGraph', {})
YIELD nodeId, score
WITH gds.util.asNode(nodeId) AS node, score
RETURN node.name AS name, node.born AS born, score
ORDER BY score DESC LIMIT 10

write、mutate 或 stats 模式不需要这样做——这些模式不会返回逐节点数据。

---

核心算法

PageRank（中心性）

CALL gds.pageRank.stream('myGraph', { dampingFactor: 0.85, maxIterations: 20 })
YIELD nodeId, score
RETURN gds.util.asNode(nodeId).name AS name, score ORDER BY score DESC LIMIT 10
// score: relative influence — not absolute. Compare within same run only.
// didConverge: true means score stabilized; if false, increase maxIterations.

CALL gds.pageRank.write('myGraph', { writeProperty: 'pagerank', dampingFactor: 0.85 })
YIELD nodePropertiesWritten, ranIterations, didConverge

pr_df = gds.page_rank.stream(G, damping_factor=0.85)
mutate_result = gds.page_rank.mutate(G, mutate_property="pagerank", damping_factor=0.85)
write_result = gds.page_rank.write(G, write_property="pagerank", damping_factor=0.85)
print(write_result.write_millis)

Louvain（社区检测）

CALL gds.louvain.stream('myGraph', { relationshipWeightProperty: 'weight' })
YIELD nodeId, communityId

CALL gds.louvain.write('myGraph', { writeProperty: 'community' })
YIELD communityCount, modularity

louvain_df = gds.louvain.stream(G)
write_result = gds.louvain.write(G, write_property="community")
print(write_result.community_count)

Leiden 是 Louvain 的改进算法，可避免形成连接不佳的社区——当社区质量比原始速度更重要时使用。 统计结果中的 modularity 范围为 -0.5 到 1.0。[field] 大于 0.3 通常表示存在有意义的社区结构；大于 0.7 则表示结构很强。 Leiden 适用于有向图和无向图。如果社区结构天然对称，请投影无向关系。

WCC — 弱连通分量

先运行 WCC 以了解图结构；在运行开销较大的算法前，先对不连通图进行分区。

CALL gds.wcc.stream('myGraph', { minComponentSize: 10 })
YIELD nodeId, componentId

CALL gds.wcc.write('myGraph', { writeProperty: 'componentId' })
YIELD nodePropertiesWritten, componentCount

wcc_df = gds.wcc.stream(G)
write_result = gds.wcc.write(G, write_property="componentId")
print(write_result.node_properties_written)

Betweenness Centrality（介数中心性）

gds.betweenness.stream(G)          # alias of betweenness_centrality; identifies bottleneck/bridge nodes
gds.betweenness.write(G, write_property="betweenness")

Node Similarity（节点相似度）

根据共同邻居计算 Jaccard 相似度——不需要节点属性。

gds.node_similarity.stream(G, similarity_cutoff=0.1, top_k=10)
gds.node_similarity.write(G, write_relationship_type="SIMILAR", write_property="score",
                          similarity_cutoff=0.1, top_k=10)

FastRP（节点嵌入）

适用于快速、可扩展的生产级 ML 流水线。设置 randomSeed 以确保结果可复现。

CALL gds.fastRP.mutate('myGraph', {
  embeddingDimension: 256,
  iterationWeights: [0.0, 1.0, 1.0],
  featureProperties: ['score'],
  propertyRatio: 0.5,
  normalizationStrength: -0.5,
  randomSeed: 42,
  mutateProperty: 'embedding'
})
YIELD nodePropertiesWritten

gds.fast_rp.mutate(G, embedding_dimension=256, iteration_weights=[0.0, 1.0, 1.0],
                   random_seed=42, mutate_property="embedding")
write_result = gds.fast_rp.write(G, embedding_dimension=256, write_property="embedding",
                                 random_seed=42)
print(write_result.write_millis)

如需对结构嵌入进行 ANN 搜索，请在 write 之后针对已写入的属性创建 Neo4j 向量索引。使用 neo4j-vector-index-skill。

KNN — K 近邻

根据节点属性（通常是嵌入），为每个节点查找最相似的 k 个节点。

CALL gds.knn.stream('myGraph', {
  nodeProperties: ['embedding'], topK: 10,
  sampleRate: 0.5, similarityCutoff: 0.7
})
YIELD node1, node2, similarity

CALL gds.knn.write('myGraph', {
  nodeProperties: ['embedding'], topK: 10,
  writeRelationshipType: 'SIMILAR', writeProperty: 'score'
})
YIELD relationshipsWritten

knn_df = gds.knn.stream(G, node_properties=["embedding"], top_k=10)
gds.knn.write(G, node_properties=["embedding"], top_k=10,
              write_relationship_type="SIMILAR", write_property="score")

---

FastRP → KNN 流水线（推荐）

# 1. Project
G, _ = gds.graph.project.native("myGraph", "Product",
    {"BOUGHT_TOGETHER": {"orientation": "UNDIRECTED"}})

# 2. Estimate memory
print(gds.fast_rp.estimate(G, embedding_dimension=128).required_memory)

# 3. Embed
gds.fast_rp.mutate(G, embedding_dimension=128, random_seed=42, mutate_property="emb")

# 4. Similarity
gds.knn.write(G, node_properties=["emb"], top_k=10,
              write_relationship_type="SIMILAR", write_property="score")

# 5. Cleanup
gds.graph.drop(G)

---

算法选择

目标	算法
通过网络链接衡量影响力	PageRank / ArticleRank
瓶颈／桥接节点	Betweenness Centrality
直接连接	Degree Centrality
社区检测（通用、快速）	Louvain
社区检测（质量更高）	Leiden
图是否连通？	WCC（先运行）
根据嵌入计算相似度	KNN
根据邻居计算相似度	Node Similarity
最短路径（正权重）	Dijkstra / A*
k 条备选路径	Yen's
快速、可扩展的嵌入	FastRP
特征丰富的节点	GraphSAGE（客户端：gds.graph_sage；Cypher：gds.beta.graphSage）

完整算法目录 → references/algorithms.md

---

常见错误

错误	原因	修复方法
Unknown function 'gds.version'	无法使用内嵌的 GDS 插件	AGA → neo4j-aura-graph-analytics-skill；自管理/本地环境 → 安装插件
GdsNotFound at client construction	目标数据库未安装 GDS 插件	安装/启用 GDS 插件；只有使用 GDS 时才能连接 AuraDS 端点
AttributeError: ... no attribute 'version'	客户端 2.0 中不存在 gds.version()	使用 gds.server_version()
DeprecationWarning at client construction	GDS 服务版本低于 2.13	升级 GDS 服务，或固定使用 graphdatascience<2 并采用 1.x 映射表
Insufficient heap memory / OOM	图对于可用的 JVM 堆内存来说过大	运行 gds.graph.project.estimate；增加 server.memory.heap.max_size
Procedure not found: gds.leiden	GDS 版本较旧或不兼容	使用 CALL gds.list() 检查可用过程；升级 GDS 或使用 Louvain
Node property 'X' not found after mutate	属性未投影，或图名称错误	验证 G.node_properties() 是否包含该属性；检查 mutate_property 拼写
Graph 'myGraph' already exists	上次运行失败后残留了投影	使用 overwrite=True、CALL gds.graph.drop('myGraph') 或 gds.graph.drop(G)
mutate_property already exists	在同一投影上重复运行算法	删除并重新投影，或使用不同的 mutate_property 名称
No algorithm results	投影中不存在源节点/目标节点	验证节点标签/关系类型是否与投影匹配；检查 G.node_count()
AttributeError: 'list' object ... after gds.graph.drop(...)	2.0 返回 list[GraphInfo]	对结果进行索引；1.x 客户端返回单个 GraphInfo
A query with 'CALL { ... } IN TRANSACTIONS' can only be executed in an implicit transaction from run_cypher	2.0 会在可重试的托管事务中运行每个查询	使用 graphdatascience>=2.1 和 run_cypher(query, auto_commit=True)

---

完整工作流

1. 使用 GraphDataScience(...) 创建 gds。
2. 验证插件：gds.server_version() 或 RETURN gds.version()。
3. 估算内存：gds.graph.project.estimate(...) 和算法的 .estimate(...)。
4. 使用 gds.graph.project.native(...) 或 gds.graph.project.cypher(query) 投影命名图。
5. 先运行 gds.*.stream；再切换到 mutate；确认满意后才使用 write。
6. 使用 gds.graph.drop(G) 删除图。
7. GDS 服务版本低于 2.13 → 通过上面的映射表使用客户端 1.22。

内置测试数据集：gds.graph.datasets.load_cora()、gds.graph.datasets.load_karate_club()、gds.graph.datasets.load_imdb()

---

MCP 工具映射

操作	MCP 工具
RETURN gds.version()	read-cypher
gds.pageRank.stream(...)	read-cypher
gds.pageRank.write(...)	write-cypher
gds.graph.drop(...)	write-cypher
列出可用过程	read-cypher → CALL gds.list()

使用任何 write-cypher 前：展示准确的 Cypher、预期受影响的节点/关系，并请求确认。对于算法的 write 模式，如果可以，先进行估算或运行 stats。

---

参考资料

• references/algorithms.md — 完整算法目录：所有过程、参数、等级，以及 Cypher + Python 示例
• references/graph-projection.md — 投影深入介绍：筛选、异构图、关系方向、属性类型
• GDS 手册
• Python 客户端文档

---

检查清单

• 已通过 gds.server_version() 或 RETURN gds.version() 确认嵌入式 GDS 插件
• 在开展大型工作前，已估算图和算法所需的内存
• Python 示例使用 2.0 端点（不带 v2 前缀）、snake_case 参数和类型化结果属性
• 仅当 GDS 服务版本低于 2.13 时，才通过映射表使用 1.x 客户端
• 投影使用原生或插件 Cypher 投影；不使用 gds.graph.project.remote(...)
• 使用后删除命名图（gds.graph.drop(G)；1.x：gds.v2.graph.drop(G)）
• 已选择执行模式：stream（检查）→ mutate（串联）→ write（持久化）
• 已检查 write_property/mutate_property 是否与现有属性冲突
• 对现有图名称重新投影时，设置 overwrite=True
• 设置 randomSeed，以确保嵌入结果可复现
• 对可能不连通的图，先运行 WCC