GDS 会话

GDS 会话是一个用于运行 GDS 工作负载的临时计算环境。它是 Neo4j 提供的一项服务，在 Neo4j 的 Aura 云平台中运行。GDS 会话通过 *远程投影* 从 Neo4j DBMS 读取数据，在投影的图上运行计算，并可选地使用 *远程回写* 将结果写回 DBMS。

GDS 会话默认不可用。请联系您的客户经理以启用这些功能。

1. GDS 会话管理

GdsSessions 对象是以下操作的 API 入口点

get_or_create：创建新的 GDS 会话或连接到现有会话。
list：列出所有当前活动的 GDS 会话。
delete：删除 GDS 会话。

您需要 Neo4j Aura API 凭据 (CLIENT_ID 和 CLIENT_SECRET) 来创建 GdsSessions 对象。有关如何从您的 Neo4j Aura 帐户创建 API 凭据的说明，请参见 Aura 文档。

创建 GdsSessions 对象

from graphdatascience.session import GdsSessions, AuraAPICredentials

CLIENT_ID = "my-aura-api-client-id"
CLIENT_SECRET = "my-aura-api-client-secret"

# Create a new GdsSessions object
sessions = GdsSessions(api_credentials=AuraAPICredentials(CLIENT_ID, CLIENT_SECRET))

1.1. 创建 GDS 会话

要创建 GDS 会话，请使用 get_or_create() 方法。如果会话不存在，它将创建一个新会话；如果会话存在，它将连接到现有会话。如果会话选项与现有会话不同，则会抛出错误。

get_or_create() 的返回值是一个 AuraGraphDataScience 对象。它提供了与 GraphDataScience 对象类似的 API，但它被配置为在 GDS 会话上运行。作为约定，始终使用变量名 gds 来表示 get_or_create() 的返回值。

1.1.1. 语法

要创建 GDS 会话，您需要提供以下信息

会话名称。名称必须是唯一的。
会话内存。此配置决定会话可用的内存和 CPU 量。它还决定运行会话的成本。可用配置列在我们 API 参考中。您可以使用 sessions.estimate() 方法来估算所需大小。
DBMS 连接。这是一个 DbmsConnectionInfo 对象，其中包含 Neo4j 实例的 URI、用户名和密码。
TTL。此可选参数指定会话的生存时间。如果会话在提供的持续时间内未使用，则会话将自动删除。使用定义为算法的计算或图的投影。
云位置。这是一个 CloudLocation 对象，它指定 GDS 会话将运行的云提供商和区域。如果 DBMS 连接是针对自管理的数据库，则需要此对象。

1.1.2. 示例

为 AuraDB 实例创建 GDS 会话

from datetime import timedelta
from graphdatascience.session import DbmsConnectionInfo, AlgorithmCategory

name = "my-new-session"
memory = sessions.estimate(
    node_count=20,
    relationship_count=50,
    algorithm_categories=[AlgorithmCategory.CENTRALITY, AlgorithmCategory.NODE_EMBEDDING],
)
db_connection_info = DbmsConnectionInfo("neo4j+s://mydbid.databases.neo4j.io", "my-user", "my-password")

gds = sessions.get_or_create(
    session_name=name,
    memory=memory,
    db_connection=db_connection_info,
    ttl=timedelta(hours=5),
)

为自管理的 Neo4j 数据库创建 GDS 会话

from datetime import timedelta
from graphdatascience.session import DbmsConnectionInfo, AlgorithmCategory, CloudLocation

name = "my-new-session-sm"
memory = sessions.estimate(
    node_count=20,
    relationship_count=50,
    algorithm_categories=[AlgorithmCategory.CENTRALITY, AlgorithmCategory.NODE_EMBEDDING],
)
db_connection_info = DbmsConnectionInfo("neo4j://#", "my-user", "my-password")
cloud_location = CloudLocation(provider="gcp", region="europe-west1")

gds = sessions.get_or_create(
    session_name=name,
    memory=memory,
    db_connection=db_connection_info,
    ttl=timedelta(hours=5),
    cloud_location=cloud_location,
)

1.2. 列出 GDS 会话

list() 方法返回所有当前活动的 GDS 会话的名称和内存大小。

列出 GDS 会话

sessions.list()

1.3. 删除 GDS 会话

使用 delete() 方法删除 GDS 会话。这将终止会话并停止任何正在运行的成本继续累积。删除会话不会影响已配置的 Neo4j 数据源。但是，任何未写回 Neo4j 实例的数据都将丢失。

删除 GDS 会话

sessions.delete(session_name="my-new-session")

2. 将图投影到 GDS 会话中

拥有 GDS 会话后，您可以将图投影到其中。此操作称为 *远程投影*，因为数据源不是一个本地数据库，而是一个远程数据库。

您可以使用 gds.graph.project() 端点、图名称、Cypher 查询和可选的附加参数来创建远程投影。Cypher 查询必须包含 gds.graph.project.remote() 函数才能将图投影到 GDS 会话中。

2.1. 语法

远程投影

gds.graph.project(
    graph_name: str,
    query: str,
    concurrency: int = 4,
    undirected_relationship_types: Optional[List[str]] = None,
    inverse_indexed_relationship_types: Optional[List[str]] = None,
): (Graph, Series[Any])

表 1. 参数
名称	可选	默认值	描述
`graph_name`	否	`-`	图的名称。
`query`	否	`-`	投影查询。
`concurrency`	是	`4`	用于在会话中构建图的并发性。
`batch_size`	是	`10000`	从 DBMS 传输到会话的批次的尺寸。
`undirected_relationship_types`	是	`[]`	应视为无向的关系类型名称列表。
`inverse_indexed_relationship_types`	是	`[]`	应反向索引的关系类型名称列表。

表 2. 结果
名称	类型	描述
`graph`	`图`	表示投影图的图对象。
`result`	`Series[Any]`	关于投影的统计数据。

concurrency 和 batch_size 配置参数可用于调整远程投影的性能。

远程投影查询的并发性由 DBMS 服务器上的 Cypher 运行时控制。使用 CYPHER runtime=parallel 作为查询前缀以最大限度地提高性能。实际使用的并发性取决于 DBMS 服务器可用的处理器和当前操作负载。

2.1.1. 远程投影查询语法

远程投影查询支持与 Cypher 投影相同的语法，但有两个主要区别

图名称不是参数。相反，图名称提供给 gds.graph.project() 端点。
必须使用 gds.graph.project.remote() 函数，而不是 gds.graph.project() 函数。

有关如何编写 Cypher 投影查询的完整详细信息和示例，请参见 GDS 手册中的 Cypher 投影文档。

2.1.2. 关系类型无向性和反向索引

可选参数 `undirectedRelationshipTypes` 和 `inverseIndexedRelationshipTypes` 用于配置关系的无向性和反向索引。这些参数的行为与 GDS 手册中所述相同。

2.2. 示例

此示例演示如何将图投影到 GDS 会话中。示例图是非同构的，它模拟用户和产品。用户可以互相认识，用户可以购买产品。数据库连接到一个新的空 AuraDB 实例。

创建 GDS 会话并向数据库添加一些数据

import os # for reading environment variables
from graphdatascience.session import SessionMemory, DbmsConnectionInfo, GdsSessions, AuraAPICredentials

sessions = GdsSessions(api_credentials=AuraAPICredentials(os.environ["CLIENT_ID"], os.environ["CLIENT_SECRET"]))

db_connection = DbmsConnectionInfo(os.environ["DB_URI"], os.environ["DB_USER"], os.environ["DB_PASSWORD"])
gds = sessions.get_or_create(
    session_name="my-new-session",
    memory=SessionMemory.m_8GB,
    db_connection=db_connection,
)

gds.run_cypher(
    """
    CREATE
     (u1:User {name: 'Mats'}),
     (u2:User {name: 'Florentin'}),
     (p1:Product {name: 'ice cream', cost: 4.2}),
     (p2:Product {name: 'computer', cost: 13.37})

    CREATE
     (u1)-[:KNOWS {since: 2020}]->(u2),
     (u2)-[:BOUGHT {price: 7474}]->(p1),
     (u1)-[:BOUGHT {price: 1337}]->(p2)
    """
)

在 `gds` GDS 会话处于活动状态的情况下，按如下方式投影图并指定节点和关系属性模式

将图投影到 GDS 会话中

G, result = gds.graph.project(
    graph_name="my-graph",
    query="""
    CALL {
        MATCH (u1:User)
        OPTIONAL MATCH (u1)-[r:KNOWS]->(u2:User)
        RETURN u1 AS source, r AS rel, u2 AS target, {} AS sourceNodeProperties, {} AS targetNodeProperties
        UNION
        MATCH (p:Product)
        OPTIONAL MATCH (p)<-[r:BOUGHT]-(user:User)
        RETURN user AS source, r AS rel, p AS target, {} AS sourceNodeProperties, {cost: p.cost} AS targetNodeProperties
    }
    RETURN gds.graph.project.remote(source, target, {
      sourceNodeProperties: sourceNodeProperties,
      targetNodeProperties: targetNodeProperties,
      sourceNodeLabels: labels(source),
      targetNodeLabels: labels(target),
      relationshipType: type(rel),
      relationshipProperties: properties(rel)
    })
    """,
)

3. 运行算法

您可以在远程投影图上以与任何投影图相同的方式运行算法。例如，您可以按如下方式在上一示例的投影图上运行 PageRank 和 FastRP 算法

运行算法并将结果流回

gds.pageRank.mutate(G, mutateProperty="pr")
gds.fastRP.mutate(G, featureProperties=["pr"], embeddingDimension=2, nodeSelfInfluence=0.1, mutateProperty="embedding")

# Stream the results back together with the `name` property fetched from the database
gds.graph.nodeProperties.stream(G, db_node_properties=["name"], node_properties=["pr", "embedding"])

有关可用算法的完整列表，请参阅 API 参考.

3.1. 限制

模型目录受限支持
- 已训练的模型只能用于使用训练它们的相同会话进行预测。会话删除后，所有已训练的模型将丢失。
- 不支持模型发布，包括
  - gds.model.publish
- 不支持模型持久性，包括
  - gds.model.store
  - gds.model.load
  - gds.model.delete
不支持拓扑链接预测算法，包括
- gds.alpha.linkprediction.adamicAdar
- gds.alpha.linkprediction.commonNeighbors
- gds.alpha.linkprediction.preferentialAttachment
- gds.alpha.linkprediction.resourceAllocation
- gds.alpha.linkprediction.sameCommunity
- gds.alpha.linkprediction.totalNeighbors

4. 远程回写

GDS 会话的内存中图是从 AuraDB 中的数据投影出来的，因此回写操作将数据持久化回相同的 AuraDB 实例。当调用任何写入操作时，GDS Python 客户端将自动使用远程回写功能。这包括所有 `.write` 算法模式以及所有 `.write` 图操作。

默认情况下，回写将并发进行，每个批次一个事务。该行为受三个方面控制

数据集的大小（例如，节点数或关系数）
配置的批次大小
配置的并发性

4.1. 语法

远程图回写

gds.graph.<operation>.write(
    graph_name: str,
    # additional parameters,
    **config: Any,
): Series[Any]

远程图回写

gds.<algo>.write(
    graph_name: str,
    **config: Any,
): Series[Any]

所有回写端点支持以下其他配置

表 3. 参数
名称	可选	默认值	描述
`concurrency`	是	dynamic ^[1]	用于回写到 DBMS 的并发性。
`arrowConfiguration`	是	-	包含从 DBMS 到 GDS Arrow 服务器的连接的附加配置的字典。
1. DBMS 服务器上处理器数量的两倍

表 4. Arrow 配置
名称	可选	默认值	描述
`batchSize`	是	`10000`	DBMS 从会话检索的批次大小。

4.2. 示例

扩展之前的示例，我们可以将 FastRP 嵌入回写到 AuraDB 实例，如下所示

将变异的 FastRP 嵌入回写到数据库

gds.graph.nodeProperties.write(G, "embedding")

如果我们想调整回写的性能，我们可以配置 `batchSize` 和 `concurrency`。在本示例中，我们将展示如何使用算法 `.write` 模式来实现这一点

计算 WCC 并将组件 ID 作为节点属性回写，并使用自定义并发配置

gds.wcc.write(
  G,
  writeProperty="wcc",
  concurrency=12,
  arrowConfiguration={"batchSize": 25000}
)

5. 查询数据库

您可以使用 `run_cypher()` 方法在 AuraDB 实例上运行 Cypher 查询。对可以运行的查询类型没有限制，但需要注意的是，查询将在 AuraDB 实例上运行，而不是在 GDS 会话上运行。因此，您将无法从 `run_cypher()` 方法中调用任何 GDS 过程。

运行 Cypher 查询以查找我们回写的嵌入

gds.run_cypher("MATCH (n:User) RETURN n.name, n.embedding")