用 Aura Graph Analytics…

在 Aura Graph Analytics GDS Session 中按会话计费地运行图算法，支持连接 AuraDB、自管 Neo4j 或独立 DataFrame/Spark 数据源。

适用场景

解决思路

1. 安装客户端：pip install "graphdatascience>=2.0"（2.0 需 Python >= 3.10、neo4j 驱动 5.26–7.0、pandas 2–3、pyarrow 21–25、numpy <3）。
2. 认证：用 GdsSessions(api_credentials=AuraAPICredentials.from_env())，从环境变量读取 AURA_CLIENT_ID、AURA_CLIENT_SECRET、AURA_PROJECT_ID（可选）；多项目时设置 AURA_PROJECT_ID 或传 project_id=。
3. 估算内存：调用 sessions.estimate(node_count=..., relationship_count=..., algorithms=[...])，可按算法名或 {算法名: 配置} 传入，也可用 algorithm_categories=[AlgorithmCategory.CENTRALITY, ...] 粗估；返回 SessionMemory 档位（m_2GB … m_512GB）。
4. 创建会话（三种模式）：AuraDB 连接用 DbmsConnectionInfo.from_env()（读 AURA_INSTANCEID 优先，否则 NEO4J_URI，加 NEO4J_USERNAME/NEO4J_PASSWORD/NEO4J_DATABASE）；自管 Neo4j 同样用 from_env() 但设 NEO4J_URI 并传 cloud_location=CloudLocation(...)；独立模式不传 db_connection，只传 memory、ttl、cloud_location。均调用 sessions.get_or_create(session_name=..., memory=..., ttl=timedelta(...))，它是幂等的，可按名重连。
5. 创建后立即调用 gds.verify_connectivity() 验证会话（及所连接的源数据库）。
6. 远程投影（连接模式）：用 gds.graph.project.cypher(graph_name="my-graph", query=query, undirected_relationship_types=["KNOWS"])，query 内部必须用 gds.graph.project.remote(source, target, {...})，多模式 MATCH 需包在 CALL () { ... } 中，多标签/关系类型用 UNION；图名传给端点而非 remote 函数；undirectedRelationshipTypes/inverseIndexedRelationshipTypes 必须作为方法参数传入，不能写在 query 里。
7. 原生远程投影（无 Cypher）：用 gds.graph.project.native("my-graph", ["Person"], ["KNOWS"], node_properties=["age","score"], undirected_relationship_types=["KNOWS"])，仅连接模式可用；需要转换/计算属性/UNION 异构模式时改用 project.cypher。
8. AuraDB Cypher API 投影：用 CYPHER runtime=parallel 加 MATCH ... RETURN gds.graph.project('my-graph', source, target, {}, { memory: '2GB' })；已有显式会话时第五个配置参数传 { sessionId: '...' }；memory、ttl、sessionId、batchSize 都放在第五个配置参数中。
9. Cypher API 会话管理：用 CALL gds.session.getOrCreate('test-session', '2GB', duration({minutes: 30})) 和 CALL gds.session.list()；隐式会话在会话内所有投影图被删除时自动删除。
10. 从 Pandas DataFrame 构造（独立模式）：用 gds.graph.construct("my-graph", [nodes_df], [rels_df])；节点必需列 nodeId(int)、labels(str)，关系必需列 sourceNodeId、targetNodeId、relationshipType；构造前删除字符串节点属性（会话只接受数值属性）。
11. 运行算法：mutate 用 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 用 gds.page_rank.stream(G) 返回 DataFrame；write 用 gds.louvain.write(G, write_property="community")（仅连接模式）。ML 流水线用 gds.pipeline.node_classification / link_prediction / node_regression。
12. 异步任务轮询：长算法用 gds.page_rank.compute(G, mutate_property="pagerank") 返回 JobHandle，循环 while not job.done(): time.sleep(5) 并打印 job.status()，确认状态为 RUNNING_DONE 后再取结果，否则抛错；用 job.result(wait=False) 取结果（未完成会抛 JobNotFinishedError）。句柄方法有 .job_id()、.status()、.done()、.wait(*, termination_flag=None)、.cancel()、.summary(...)、.result(wait=False)。异步投影返回 ProjectionJobHandle（gds.graph.project.native_async(...)、cypher_async(...)），写回返回 WriteJobHandle；用 gds.jobs.list() 列出任务、gds.jobs.get(G, job_id) 恢复句柄。
13. 取回结果：用 gds.graph.node_properties.stream(G, node_properties=["pagerank","embedding"], db_node_properties=["name"])（db_node_properties 仅连接模式，用于取字符串属性）；独立模式无 db_node_properties，改为与源 DataFrame 合并：result_df.merge(nodes_df[["nodeId","name"]], how="left")。
14. 写回与清理：用 gds.graph.node_properties.write(G, ["pagerank","embedding"]) 写节点属性、gds.graph.relationships.write(G, "SIMILAR", ["score"]) 写关系属性、gds.run_cypher("MATCH (n:Person) RETURN count(n)") 查询连接库；用 gds.graph.drop(G) 删除投影图；用 sessions.delete(session_name="my-analysis") 或 gds.delete() 删除会话。删除前必须先写回或流式保存结果，否则结果丢失。
15. 会话管理：用 DataFrame(sessions.list()) 列出活跃会话；用 sessions.get_or_create(session_name="my-analysis", memory=..., db_connection=...) 重连已有会话。
16. 设置 TTL 避免空闲会话产生意外费用（默认空闲 1 小时，最长 7 天硬上限）；完成后删除会话以停止计费。
17. 处理常见错误：401/AuthenticationError 重新在 Aura Console → Account → API credentials 生成凭据；会话过期用 sessions.list() 检查并重建；GraphNotFoundError 重新投影；独立会话远程投影报 ValueError 时改用 gds.graph.construct(...)；NotAvailableInStandaloneSessions 需附加数据库或换算法；算法 FAILED 时提升 SessionMemory 档位；MemoryEstimationExceeded 用实际计数重新估算并升档；字符串节点属性报错时先删除字符串列，之后用 db_node_properties 取回。
18. 1.x 迁移映射：gds.v2.<endpoint> → gds.<endpoint>（去掉 v2 前缀）；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；failIfMissing= → fail_if_missing=；gds.v2.verify_session_connectivity()/verify_db_connectivity() → gds.verify_connectivity()；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。
19. 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]。
20. 按需加载参考文档：references/workflows.md（完整 AuraDB 与独立工作流、Spark 集成）、references/limitations.md（AGA 与嵌入式 GDS 功能对比、SessionMemory 档位、云区域）。
21. 需要时用 WebFetch 查阅：AGA Python 客户端文档、AGA Cypher API 文档、客户端 1.x→2.0 迁移指南、AuraDB 教程 notebook、GDS 算法参考。

适用边界 · 注意事项

• Aura Pro 或自管 Neo4j 上使用嵌入式 GDS 插件时，应改用 neo4j-gds-skill。
• 需要编写 Cypher 查询时，应改用 neo4j-cypher-skill。
• 使用 Snowflake Graph Analytics 时，应改用 neo4j-snowflake-graph-analytics-skill。