入门指南

Python 客户端的设计理念是在 Python 代码中模拟 GDS Cypher API。Python 客户端会将用户编写的 Python 代码转换为相应的 Cypher 查询，然后使用 Neo4j Python 驱动程序连接在 Neo4j 服务器上运行该查询。

Python 客户端力求尽可能“Python 化”，以最大限度地方便习惯并精通 Python 环境的用户。因此，我们尽可能地使用标准的 Python 类型和 pandas 类型。然而，为了与 Cypher 接口保持一致，调用对应于 Cypher 过程的方法时，通用返回值将以表（Python 中的 pandas DataFrame）的形式呈现。有关此内容的详细信息，请参阅Cypher 与 Python 之间的映射。

Python 客户端的核心组件是 GraphDataScience 对象。一旦实例化，它就构成了与 GDS 库交互的入口点。这包括在 GDS 中投影图、运行算法以及定义和使用机器学习管道。按照惯例，我们建议始终将实例化的 GraphDataScience 对象命名为 gds，因为这样使用起来最接近直接使用 Cypher API。

1. 导入与设置

实例化 GraphDataScience 对象的最简单方法是使用 Neo4j 服务器 URI 和相应的凭据。

from graphdatascience import GraphDataScience

# Use Neo4j URI and credentials according to your setup
# NEO4J_URI could look similar to "bolt://my-server.neo4j.io:7687"
gds = GraphDataScience(NEO4J_URI, auth=(NEO4J_USER, NEO4J_PASSWORD))

# Check the installed GDS version on the server
print(gds.server_version())
assert gds.server_version()

结果

"2.1.9"

请注意，GraphDataScience 对象在构建时需要与 Neo4j 数据库进行通信，并且默认使用 "neo4j" 数据库。如果没有该数据库，您将需要使用 database 关键字参数提供一个有效的数据库。

1.1. Aura 图分析 (Aura Graph Analytics)

GDS Python 客户端对 Aura 图分析产品提供了专门的支持。

此示例展示了如何使用 Aura API 密钥对和 AuraDB 连接信息来实例化 GraphDataScience 对象。

from graphdatascience.session import DbmsConnectionInfo, GdsSessions, AuraAPICredentials, SessionMemory

sessions = GdsSessions(api_credentials=AuraAPICredentials("<clientId>", "<clientSecret>"))
gds = sessions.get_or_create(
    session_name="my-session",
    memory=SessionMemory.m_4GB,
    db_connection=DbmsConnectionInfo("neo4j+s://mydbid.databases.neo4j.io", "neo4j", "<password>"),
)

1.2. AuraDS

如果您将客户端连接到 AuraDS 实例，则可以自动应用推荐的 Python 驱动程序非默认配置设置。为此，请设置构造函数参数 aura_ds=True。

from graphdatascience import GraphDataScience

# Configures the driver with AuraDS-recommended settings
gds = GraphDataScience(
    "neo4j+s://my-aura-ds.databases.neo4j.io:7687",
    auth=("neo4j", "my-password"),
    aura_ds=True
)

1.3. 从 Neo4j 驱动程序实例化

对于某些用例，需要直接访问和控制 Neo4j 驱动程序。例如，如果需要以特定方式配置所使用的 Neo4j 驱动程序。在这种情况下，可以使用 GraphDataScience.from_neo4j_driver 方法来实例化 GraphDataScience 对象。它采用与常规 GraphDataScience 构造函数相同的参数，但 aura_ds 关键字参数除外，该参数仅在内部实例化底层的 Neo4j 驱动程序时才相关。

1.4. 检查许可证状态

要检查我们正在运行的 GDS 服务器库是否具有企业版许可证，可以进行以下调用：

using_enterprise = gds.is_licensed()

1.5. 指定目标数据库

如果我们不想使用 DBMS 的默认数据库，可以为 GraphDataScience 构造函数提供关键字参数 database。

gds = GraphDataScience(NEO4J_URI, auth=(NEO4J_USER, NEO4J_PASSWORD), database="my-db")

或者我们也可以在稍后更改我们要定位的数据库。

gds.set_database("my-db")

1.6. 配置 Apache Arrow 参数

如果服务器上提供了 Apache Arrow，我们可以为 GraphDataScience 构造函数提供几个关键字参数来配置连接。

arrow_disable_server_verification：一个标志，指示如果 Flight 客户端使用 TLS 连接，则跳过服务器验证。如果启用了此功能，则会覆盖所有其他 TLS 设置。
arrow_tls_root_certs：用于连接到 Apache Arrow Flight 服务器的 PEM 编码证书。

gds = GraphDataScience(
  NEO4J_URI,
  auth=(NEO4J_USER, NEO4J_PASSWORD),
  arrow=True,
  arrow_disable_server_verification=False,
  arrow_tls_root_certs=CERT
)

2. 最小示例

在以下示例中，我们演示了 Python 客户端运行 Cypher 查询、将图投影到 GDS 中、运行算法以及通过客户端图对象检查结果的过程。我们假设已经创建了一个存储在变量 gds 中的 GraphDataScience 对象。

# Create a minimal example graph
gds.run_cypher(
  """
  CREATE
  (m: City {name: "Malmö"}),
  (l: City {name: "London"}),
  (s: City {name: "San Mateo"}),
  (m)-[:FLY_TO]->(l),
  (l)-[:FLY_TO]->(m),
  (l)-[:FLY_TO]->(s),
  (s)-[:FLY_TO]->(l)
  """
)

# Project the graph into the GDS Graph Catalog
# We call the object representing the projected graph `G_office`
G_office, project_result = gds.graph.project("neo4j-offices", "City", "FLY_TO")

# Run the mutate mode of the PageRank algorithm
mutate_result = gds.pageRank.mutate(G_office, tolerance=0.5, mutateProperty="rank")

# We can inspect the node properties of our projected graph directly
# via the graph object and see that indeed the new property exists
assert G_office.node_properties("City") == ["rank"]

您也可以使用库附带的数据集之一来开始使用。有关更多信息，请参阅数据集 (Datasets) 章节。

客户端库的设计方式使得大多数方法在您输入时通过字符串构建方案和重载魔术方法 __getattr__ 在底层进行推断。因此，大多数方法（例如 pageRank）在调用 dir(gds) 时不会出现。同样，IDE 和语言服务器将无法自动检测这些推断出的方法，这意味着它们提供的自动补全支持将受到限制。但请放心，尽管缺乏这种可发现性，但推断出的方法（例如 gds.pageRank.stream）仍然可以被正确调用。

3. 运行 Cypher

正如我们在上面的示例中看到的那样，GraphDataScience 对象有一个用于便捷运行 Cypher 查询的方法 run_cypher。此方法将查询字符串 query: str、可选的 Cypher 参数字典 params: Optional[Dict[str, Any]] 以及用于覆盖目标数据库的可选字符串 database: Optional[str] 作为参数。它以 pandas DataFrame 的格式返回查询结果。

4. 关闭打开的连接

与 Neo4j Python 驱动程序支持关闭所有到 DBMS 的打开连接类似，您可以在 GraphDataScience 对象上调用 close 来实现相同的效果。

# Close any open connections in the underlying Neo4j driver's connection pool
gds.close()

当 GraphDataScience 对象被删除时，close 也会被自动调用。

5. Cypher 与 Python 之间的映射

Cypher API 如何映射到 Python 客户端 API 有一些通用原则。

对应于 Cypher 过程（文档中以 CALL 开头）的方法调用会返回：
- 如果过程返回多行（例如流模式算法调用），则返回一个作为 pandas DataFrame 的表。
- 如果过程只返回一行（例如统计模式算法调用），则返回一个作为 pandas Series 的行。
其中一些值得注意的例外是：
- 实例化图对象和模型对象的过程有两个返回值：图或模型对象，以及来自底层过程调用的元数据行（通常是 pandas Series）。
- 任何在管道、图或模型对象（Python 客户端原生）上映射到 Cypher 过程的方法。
- gds.version()，它返回一个字符串。
对应于 Cypher 函数（文档中以 RETURN 开头）的方法调用将简单地返回该函数所返回的值。
Python 客户端还包含使用客户端侧图对象检查 GDS 图目录中图的特定功能。同样，可以使用客户端侧模型对象来检查 GDS 模型目录中的模型。
GDS 中那些以图和/或模型引用字符串作为输入的 Cypher 函数和过程，在 Python 客户端 API 中通常改为接受图对象和/或模型对象作为输入。
为了在 GDS 中配置和使用机器学习管道，Python 客户端中使用特定的管道对象。