Cypher API

Aura 图分析 (Graph Analytics) 的 Cypher API 与 GDS 插件 API 尽可能保持一致。除了一些限制外，您可以应用文档其余部分中的大多数示例。

现在，您可以在 AuraDB 内部使用 Cypher API，而无需 Aura API 凭据。

投影图 (Projecting a graph)

Aura 图分析不支持原生投影 (Native projections) 和旧版 Cypher 投影。

使用带有附加身份验证子句的 Cypher 投影，将图投影到 GDS 会话中。

确保在创建会话的同时，包含带有 Aura Graph Analytics 标签的附加参数。

将图投影到新的 GDS 会话中

CYPHER runtime=parallel (1)
MATCH (source)
OPTIONAL MATCH (source)-->(target)
RETURN gds.graph.project('g',
  source,
  target,
  {},
  { memory: '2GB' } (2)
)

1	建议使用 Cypher `parallel` 运行时，但这并非强制要求。
2	包含与会话相关参数（例如 `memory`，必填）的映射。

如果您已显式创建了会话，请添加 sessionId 参数作为会话 ID，以使用该现有会话。

将图投影到现有的 GDS 会话中

CYPHER runtime=parallel (1)
MATCH (source)
OPTIONAL MATCH (source)-->(target)
RETURN gds.graph.project('g',
  source,
  target,
  {},
  { sessionId: '00000000-11111111' }
)

1	建议使用 Cypher `parallel` 运行时，但这并非强制要求。

运行算法

有关不支持的算法列表，请参阅限制部分。

Aura 图分析的 Cypher API 支持所有现有执行模式中的大多数算法和机器学习操作。其语法与 GDS 插件相同，并增加了身份验证子句。

在 stream 模式下调用算法过程

CALL gds.pageRank.stream('g')

会话管理

会话管理过程允许显式创建不附带任何图的新会话，或者列出并删除现有会话。

创建会话

调用 gds.session.getOrCreate 过程会根据指定的参数触发 GDS 会话的创建。如果具有给定名称和配置的会话已存在，则直接返回该会话。

创建一个空的 GDS 会话

CALL gds.session.getOrCreate(
  'test-session',
  '2GB',
  duration({minutes: 30})
)
YIELD name
RETURN name

表 1. 结果
名称 (name)
"test-session"

当您通过 gds.session.getOrCreate 显式创建会话时，请记下 sessionId，并在投影新图时将其设置为 gds.graph.project 过程的配置参数。

语法

CALL gds.session.getOrCreate(
  sessionName: String,
  memory: String,
  ttl: Duration
  cloudLocation: Map
) YIELD
  id: String,
  name: String,
  auraInstanceId: String,
  memory: String,
  status: String,
  creationTime: Datetime,
  host: String,
  expiryDate: Datetime,
  ttl: TemporalAmount,
  errorMessage: String

表 2. 参数
名称	类型	可选	描述
sessionName	字符串	否	要创建或返回的 GDS 会话名称。
memory	字符串	否	GDS 会话的大小，例如 `4GB`、`8GB` 等。
TTL (存活时间)	Duration	是	当没有记录到活动时，GDS 会话的生存时间 (TTL)，例如 `duration({days: 1})`、`duration({hours: 12})` 等。默认值为 1 小时。

表 3. 结果
名称	类型	描述
`id`	字符串	GDS 会话的唯一标识符。
`名称 (name)`	字符串	GDS 会话的名称。
`auraInstanceId`	字符串	GDS 会话所附属的 Aura 实例 ID。
`memory`	字符串	GDS 会话的大小，例如 `4GB`、`8GB` 等。
`状态 (status)`	字符串	GDS 会话的状态，例如 `Creating`（创建中）、`Ready`（就绪）、`Expired`（已过期）等。
`creationTime`	Datetime	GDS 会话创建的时间。
`host`	字符串	GDS 会话的公共主机地址。
`expiryDate`	Datetime	GDS 会话最终过期的确定时间。
`TTL (存活时间)`	TemporalAmount	因不活动而导致 GDS 会话过期前的剩余时间。
`errorMessage`	字符串	如果 GDS 会话无法创建或处于不健康状态，则显示的错误消息。

列出会话

gds.session.list 过程返回当前 Aura 用户可用的所有 GDS 会话。

语法

CALL gds.session.list(
  projectId: String,
  filterAuraInstanceId: boolean
) YIELD
  id: String,
  name: String,
  auraInstanceId: String,
  memory: String,
  status: String,
  creationTime: Datetime,
  host: String,
  expiryDate: Datetime,
  ttl: TemporalAmount,
  errorMessage: String

表 4. 参数
名称	类型	可选	默认	描述
项目 ID (projectId)	字符串	是	""	GDS 会话所属的项目 ID。如果未指定，将返回 Aura 用户的所有会话。
filterAuraInstance	字符串	是	false	如果设置为 `true`，则仅返回附属当前 Aura 实例的会话。如果未指定，则返回用户的所有会话。请注意，这仅在通过 Aura API 凭据进行身份验证时才有意义。

表 5. 结果
名称	类型	描述
`id`	字符串	GDS 会话的唯一标识符。
`名称 (name)`	字符串	GDS 会话的名称。
`auraInstanceId`	字符串	GDS 会话所附属的 Aura 实例 ID。
`memory`	字符串	GDS 会话的大小，例如 `4GB`、`8GB` 等。
`状态 (status)`	字符串	GDS 会话的状态，例如 `Creating`（创建中）、`Ready`（就绪）、`Expired`（已过期）等。
`creationTime`	Datetime	GDS 会话创建的时间。
`host`	字符串	GDS 会话的公共主机地址。
`expiryDate`	Datetime	GDS 会话最终过期的确定时间。
`TTL (存活时间)`	TemporalAmount	因不活动而导致 GDS 会话过期前的剩余时间。
`errorMessage`	字符串	如果 GDS 会话无法创建或处于不健康状态，则显示的错误消息。

删除会话

gds.session.delete 过程删除具有给定 ID 的 GDS 会话。如果未找到该会话，则会引发错误。

CALL gds.session.delete(
  'test-session'
)
YIELD deleted
RETURN deleted

表 6. 结果
deleted
true

语法

CALL gds.session.delete(
  name: String,
  projectId: String
) YIELD
  deleted: boolean

表 7. 参数
名称	类型	可选	默认	描述
名称 (name)	字符串	否	不适用	要删除的 GDS 会话名称。
项目 ID (projectId)	字符串	是	""	GDS 会话所属的项目 ID。如果不同项目中存在相似的会话，则会抛出错误，提示提供项目 ID。

表 8. 结果
名称	类型	描述
deleted	布尔值	如果 GDS 会话已成功删除，则为 True，否则为 false。

限制

与 GDS 插件相比，Aura 图分析的 Cypher API 存在一些限制。

如果您通过 GDS Python 客户端使用 Aura 图分析，其中一些限制可能不适用。有关详细信息，请参阅 Python 客户端文档。

算法

以下算法不受支持：

其他过程和函数

Aura 图分析的 Cypher API 不支持 GDS 插件中提供的所有过程和函数。此处提到的一些内容将来可能会得到支持，而其他内容可能永远不会得到支持。

图目录

以下图目录过程不受支持：

gds.graph.project
gds.graph.project.estimate
gds.graph.project.cypher
gds.graph.project.cypher.estimate
gds.graph.export
gds.graph.export.csv
gds.graph.export.csv.estimate
gds.backup
gds.restore
gds.graph.graphProperty.drop
gds.graph.graphProperty.stream

机器学习

训练好的模型只能在训练它们时所在的同一会话中用于预测。会话删除后，所有训练好的模型都将丢失。

以下机器学习过程不受支持：

gds.model.publish
gds.model.store
gds.model.load
gds.model.delete
gds.linkprediction.adamicAdar
gds.linkprediction.commonNeighbors
gds.linkprediction.preferentialAttachment
gds.linkprediction.resourceAllocation
gds.linkprediction.sameCommunity
gds.linkprediction.totalNeighbors
gds.splitRelationships

此外，所有 pipeline 过程均不受支持。

附加操作

以下附加操作不受支持：

gds.license.state
gds.debug.arrow
gds.debug.sysInfo
gds.license.state
gds.userLog
gds.version
gds.util.nodeProperty

显式验证 Aura API

当直接在 AuraDB 实例中执行 Cypher 查询时，您会自动获得创建和管理自己的 Aura 图分析会话的权限，无需提供显式的 API 凭据。

仅在以下两种特定情况下，需要通过 Aura API 凭据进行显式身份验证：

项目范围管理 (Cypher)：您正在使用 Cypher，并且需要管理整个 Aura 控制台项目中所有会话的生命周期操作（例如列出或删除），而不仅仅是您当前登录的数据库用户所创建的会话。在这种情况下，您必须在每个 Cypher 查询中使用 gds.aura.api.credentials() 函数。
使用 Python 客户端：如果您使用专用的 GDS Python 库来编排会话，则客户端需要 Aura API 凭据来验证控制平面。有关说明，请参阅 Neo4j 图数据科学客户端文档。

对于凭据等敏感数据，使用查询参数是一种良好的做法。这也消除了多次输入相同字符串的需要。

在 Aura 控制台中，您可以在查询工具 (Query tool) 中设置查询参数。对于其他环境，请参阅 Cypher 手册。

gds.aura.api.credentials 的使用

WITH gds.aura.api.credentials($clientId, $clientSecret) AS credentials (1)
MATCH (source)
OPTIONAL MATCH (source)-->(target)
RETURN gds.graph.project('g',
  source,
  target,
  {},
  { memory: '4GB' }
)

1	只要指定了别名，您可以使用任何别名。

该函数不返回任何值，而是将凭据注册到查询上下文中。凭据不会保存在任何地方，并且在查询完成后立即被丢弃。

如果您在此管理上下文中进行操作，则必须在与会话交互的每个查询中包含凭据函数。例如，如果您使用显式凭据创建了图，则尝试在新查询中运行算法而不再次传递凭据将会失败。

在没有 Aura API 凭据的情况下调用算法过程

CALL gds.wcc.stream('g') // This alone will not work

语法

RETURN gds.aura.api.credentials(
  clientId: String,
  clientSecret: String
) AS credentials

表 9. 配置
名称	类型	默认	可选	描述
clientId	字符串	`不适用`	否	Aura API 密钥对的客户端 ID。
clientSecret	字符串	`不适用`	否	Aura API 密钥对的客户端密钥。

表 10. 结果
名称	类型	描述
-	-	始终返回 `null`。