用途
本技能用于在 Neo4j Aura 的 Serverless Aura Graph Analytics（AGA）GDS Session 中运行 GDS 图算法。典型使用场景包括：
- 在 AGA GDS Session 中运行 GDS 算法
- 创建 GdsSessions 或使用 AuraGraphDataScience
- 使用 gds.graph.project.remote(...) 远程投影已连接的 Neo4j 数据
- 使用 AuraDB Cypher API 投影，并传入 { memory: ... } 或 { sessionId: ... }
- 处理来自非 Neo4j 数据源（Pandas、Spark、CSV）的图数据
- 按需或流水线负载：临时会话，按会话分钟计费
- 在分析期间与实时数据库完全隔离
不适用场景：Aura Pro 内嵌 GDS 插件（改用 neo4j-gds-skill）、自管理 Neo4j 内嵌 GDS 插件（neo4j-gds-skill）、编写 Cypher 查询（neo4j-cypher-skill）、Snowflake Graph Analytics（neo4j-snowflake-graph-analytics-skill）。
部署选择
- AuraDB Free：本技能，最大 m_2GB，1 个并发会话，不计费
- Aura Pro + 启用 Graph Analytics 插件（轻量探索、共享资源）：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）：本技能（standalone 模式）
默认约定
- 要求 graphdatascience >= 2.0，推荐 >= 2.1
- 2.0 端点无 v2 前缀
- 端到端使用 snake_case 参数
- 会话创建后调用 gds.verify_connectivity()
- 大会话前先估算内存
- 设置 TTL；默认空闲 1 小时，最长 7 天（硬性 7 天上限）
- 完成后关闭会话：gds.delete() 或 sessions.delete(session_name=...)
- 使用 AuraAPICredentials.from_env() 和 DbmsConnectionInfo.from_env()，切勿硬编码凭据
安装
pip install "graphdatascience>=2.1"
2.0 / 2.1 要求：Python >= 3.10、neo4j 驱动 5.26–7.0、pandas 2–3、pyarrow 21–25、numpy <3。
主要能力
- 认证：GdsSessions(api_credentials=AuraAPICredentials.from_env())，读取 AURA_CLIENT_ID、AURA_CLIENT_SECRET、AURA_PROJECT_ID
- 内存估算：sessions.estimate(node_count=..., relationship_count=..., algorithms=[...])
- 创建会话：sessions.get_or_create(session_name=..., memory=..., db_connection=..., ttl=...)，支持 AuraDB 连接模式、自管理 Neo4j 模式、standalone 模式
- 图投影：gds.graph.project.cypher(...)（远程）、gds.graph.project.native(...)、AuraDB Cypher API 投影、从 Pandas DataFrame 的 gds.graph.construct(...)
- 运行算法：mutate / stream / write 三种模式
- 异步任务轮询：job.done()、job.status()、job.result(wait=False)
- 结果检索：gds.graph.node_properties.stream(...)，可配合 db_node_properties 获取字符串属性
- 写回与清理：gds.graph.node_properties.write(...)、gds.graph.relationships.write(...)、gds.graph.drop(G)、sessions.delete(...)
使用方式（要点）
- 认证并读取环境变量中的凭据
- 估算内存选择 SessionMemory 层级
- 创建或复用会话（get_or_create 幂等）
- 投影图（远程 / native / Cypher API / DataFrame）
- 运行算法并轮询异步任务
- 检索结果并写回，最后删除会话
适用场景与限制
- standalone 会话无法远程投影（需用 gds.graph.construct）
- 会话仅支持数值节点属性；字符串属性需投影后通过 db_node_properties 获取
- 部分功能仅限已连接数据库的会话
- 结果必须在会话关闭前写入或流式取出
- 需在 Aura Console 项目中启用 AGA 功能
参考链接
- 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/
- GDS 算法参考：https://neo4j.com/docs/graph-data-science/current/algorithms/