入门

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.version())
assert gds.version()
结果
"2.1.9"

请注意，GraphDataScience 对象需要在构建时与 Neo4j 数据库通信，并且默认情况下使用默认的“neo4j”数据库。如果没有此类数据库，您将需要 使用 database 关键字参数提供有效的数据库。

1.1. AuraDS

如果您将客户端连接到 AuraDS 实例，则可以自动获取 Python 驱动程序的推荐非默认配置设置。要实现这一点，请将构造函数参数 aura_ds=True 设置为 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.2. 从 Neo4j 驱动程序实例化

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

1.3. 检查许可证状态

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

using_enterprise = gds.is_licensed()

1.4. 指定目标数据库

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

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

或者，我们可以更改我们后来要定位的数据库

gds.set_database("my-db")

1.5. 配置 Apache Arrow 参数

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

  • arrow_disable_server_verification：一个标志，指示如果飞行客户端使用 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"]
您也可以使用库附带的数据集之一开始。有关这方面的更多信息，请参阅 数据集 章节。

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

3. 运行 Cypher

正如我们在 上面的示例 中看到的，GraphDataScience 对象有一个名为 run_cypher 的方法，用于方便地运行 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）。

    • 任何与 Cypher 过程相对应的 管道、图 或 模型 对象（Python 客户端原生）上的方法。

    • gds.version() 返回一个字符串。

  • 与 Cypher 函数相对应的函数调用（在文档中以 RETURN 开头）将简单地返回函数返回的值。

  • Python 客户端还包含用于从 GDS 图目录 检查图的特定功能，使用客户端 图对象。同样，可以使用客户端 模型对象 检查来自 GDS 模型目录 的模型。

  • 在 GDS 中，接受图和/或模型引用作为字符串输入的 Cypher 函数和过程，通常在 Python 客户端 API 中接受 图对象 和/或 模型对象 作为输入。

  • 为了配置和使用 GDS 中的 机器学习管道，在 Python 客户端中使用了特定的 管道对象。