CALL gds.shortestPath.astar.stream(
  graphName: String,
  configuration: Map
)
YIELD
  index: Integer,
  sourceNode: Integer,
  targetNode: Integer,
  totalCost: Float,
  nodeIds: List of Integer,
  costs: List of Float,
  path: Path

表 1. 参数
名称	类型	默认值	可选	描述
graphName	字符串	`不适用`	否	目录中存储的图的名称。
configuration	映射	`{}`	是	算法特定和/或图过滤的配置。

表 2. 配置
名称	类型	默认值	可选	描述
nodeLabels	字符串列表	`['*']`	是	使用给定节点标签过滤命名图。将包含具有任何给定标签的节点。
relationshipTypes	字符串列表	`['*']`	是	使用给定关系类型过滤命名图。将包含具有任何给定类型的关系。
concurrency	整数	`4 ^[1]`	是	用于运行算法的并发线程数。
jobId	字符串	`内部生成`	是	一个 ID，可以提供此 ID 以更轻松地跟踪算法的进度。
logProgress	布尔值	`true`	是	如果禁用，则不会记录进度百分比。
sourceNode	整数	`不适用`	否	Neo4j 源节点或节点 ID。
targetNode	整数	`不适用`	否	Neo4j 目标节点或节点 ID。
latitudeProperty	浮点数	`不适用`	否	存储纬度值的节点属性。
longitudeProperty	浮点数	`不适用`	否	存储经度值的节点属性。
relationshipWeightProperty	字符串	`null`	是	用作权重的关系属性名称。如果未指定，算法将无加权运行。
1. 在 GDS 会话中，默认值为可用处理器数量

表 3. 结果
名称	类型	描述
index	整数	找到路径的 0-based 索引。
sourceNode	整数	路径的源节点。
targetNode	整数	路径的目标节点。
totalCost	浮点数	从源到目标的总成本。
nodeIds	整数列表	按遍历顺序排列的路径上的节点 ID。
costs	浮点数列表	路径上每个节点的累计成本。
path	路径	以 Cypher 实体表示的路径。

mutate 模式在投影图中创建新关系。每个关系代表从源节点到目标节点的路径。路径的总成本通过 totalCost 关系属性存储。

在命名图上以 mutate 模式运行 A*。

CALL gds.shortestPath.astar.mutate(
  graphName: String,
  configuration: Map
)
YIELD
  relationshipsWritten: Integer,
  preProcessingMillis: Integer,
  computeMillis: Integer,
  postProcessingMillis: Integer,
  mutateMillis: Integer,
  configuration: Map

表 4. 参数
名称	类型	默认值	可选	描述
graphName	字符串	`不适用`	否	目录中存储的图的名称。
configuration	映射	`{}`	是	算法特定和/或图过滤的配置。

表 5. 配置
名称	类型	默认值	可选	描述
mutateRelationshipType	字符串	`不适用`	否	用于写入投影图的新关系的关系类型。
nodeLabels	字符串列表	`['*']`	是	使用给定节点标签过滤命名图。
relationshipTypes	字符串列表	`['*']`	是	使用给定关系类型过滤命名图。
concurrency	整数	`4`	是	用于运行算法的并发线程数。
jobId	字符串	`内部生成`	是	一个 ID，可以提供此 ID 以更轻松地跟踪算法的进度。
sourceNode	整数	`不适用`	否	Neo4j 源节点或节点 ID。
targetNode	整数	`不适用`	否	Neo4j 目标节点或节点 ID。
latitudeProperty	浮点数	`不适用`	否	存储纬度值的节点属性。
longitudeProperty	浮点数	`不适用`	否	存储经度值的节点属性。
relationshipWeightProperty	字符串	`null`	是	用作权重的关系属性名称。如果未指定，算法将无加权运行。

表 6. 结果
名称	类型	描述
preProcessingMillis	整数	预处理图的毫秒数。
computeMillis	整数	运行算法的毫秒数。
postProcessingMillis	整数	未使用。
mutateMillis	整数	向投影图添加关系的毫秒数。
relationshipsWritten	整数	已添加关系的数目。
configuration	映射	用于运行算法的配置。

write 模式在 Neo4j 数据库中创建新关系。每个新关系代表从源节点到目标节点的路径。附加路径信息使用关系属性存储。默认情况下，write 模式存储 totalCost 属性。可选地，还可以存储路径上中间节点的 nodeIds 和 costs。

在命名图上以 write 模式运行 A*。

CALL gds.shortestPath.astar.write(
  graphName: String,
  configuration: Map
)
YIELD
  relationshipsWritten: Integer,
  preProcessingMillis: Integer,
  computeMillis: Integer,
  postProcessingMillis: Integer,
  writeMillis: Integer,
  configuration: Map

表 7. 参数
名称	类型	默认值	可选	描述
graphName	字符串	`不适用`	否	目录中存储的图的名称。
configuration	映射	`{}`	是	算法特定和/或图过滤的配置。

表 8. 配置
名称	类型	默认值	可选	描述
nodeLabels	字符串列表	`['*']`	是	使用给定节点标签过滤命名图。将包含具有任何给定标签的节点。
relationshipTypes	字符串列表	`['*']`	是	使用给定关系类型过滤命名图。将包含具有任何给定类型的关系。
concurrency	整数	`4 ^[2]`	是	用于运行算法的并发线程数。
jobId	字符串	`内部生成`	是	一个 ID，可以提供此 ID 以更轻松地跟踪算法的进度。
logProgress	布尔值	`true`	是	如果禁用，则不会记录进度百分比。
writeConcurrency	整数	`'concurrency' 的值`	是	用于将结果写入 Neo4j 的并发线程数。
writeRelationshipType	字符串	`不适用`	否	用于将计算的关系持久化到 Neo4j 数据库中的关系类型。
sourceNode	整数	`不适用`	否	Neo4j 源节点或节点 ID。
targetNode	整数	`不适用`	否	Neo4j 目标节点或节点 ID。
latitudeProperty	浮点数	`不适用`	否	存储纬度值的节点属性。
longitudeProperty	浮点数	`不适用`	否	存储经度值的节点属性。
relationshipWeightProperty	字符串	`null`	是	用作权重的关系属性名称。如果未指定，算法将无加权运行。
writeNodeIds	布尔值	`false`	是	如果为 true，则写入的关系具有 nodeIds 列表属性。
writeCosts	布尔值	`false`	是	如果为 true，则写入的关系具有 costs 列表属性。
2. 在 GDS 会话中，默认值为可用处理器数量

表 9. 结果
名称	类型	描述
preProcessingMillis	整数	预处理图的毫秒数。
computeMillis	整数	运行算法的毫秒数。
postProcessingMillis	整数	未使用。
writeMillis	整数	将关系写入 Neo4j 的毫秒数。
relationshipsWritten	整数	已写入关系的数目。
configuration	映射	用于运行算法的配置。

示例

以下所有示例都应在空数据库中运行。

示例使用Cypher 投影作为规范。原生投影将在未来的版本中弃用。

在本节中，我们将演示如何在具体图上运行 A* 算法的示例。目的是说明结果的样式，并提供在实际设置中如何使用该算法的指南。我们将在一个小型传输网络图上进行此操作，该图包含少量按特定模式连接的节点。示例图如下所示：

以下 Cypher 语句将在 Neo4j 数据库中创建示例图：

CREATE (a:Station {name: 'Kings Cross',         latitude: 51.5308, longitude: -0.1238}),
       (b:Station {name: 'Euston',              latitude: 51.5282, longitude: -0.1337}),
       (c:Station {name: 'Camden Town',         latitude: 51.5392, longitude: -0.1426}),
       (d:Station {name: 'Mornington Crescent', latitude: 51.5342, longitude: -0.1387}),
       (e:Station {name: 'Kentish Town',        latitude: 51.5507, longitude: -0.1402}),
       (a)-[:CONNECTION {distance: 0.7}]->(b),
       (b)-[:CONNECTION {distance: 1.3}]->(c),
       (b)-[:CONNECTION {distance: 0.7}]->(d),
       (d)-[:CONNECTION {distance: 0.6}]->(c),
       (c)-[:CONNECTION {distance: 1.3}]->(e)

该图表示一个车站的交通网络。每个车站都有一个地理坐标，通过 latitude 和 longitude 属性表示。车站通过连接相互连接。我们使用 distance 属性作为关系权重，它表示车站之间的距离（以千米为单位）。算法将根据已行驶距离和到目标车站的距离选择搜索中的下一个节点。

以下语句将使用 Cypher 投影投影一个图，并将其以名称“myGraph”存储在图目录中。

MATCH (source:Station)-[r:CONNECTION]->(target:Station)
RETURN gds.graph.project(
  'myGraph',
  source,
  target,
  {
    sourceNodeProperties: source { .latitude, .longitude },
    targetNodeProperties: target { .latitude, .longitude },
    relationshipProperties: r { .distance }
  }
)

在以下示例中，我们将演示如何使用此图的 A* 最短路径算法。

内存估算

首先，我们将使用 estimate 过程估算运行算法的成本。这可以通过任何执行模式完成。在此示例中，我们将使用 write 模式。估算算法有助于了解运行算法对图的内存影响。当您随后实际以某种执行模式运行算法时，系统将执行估算。如果估算表明执行超出内存限制的可能性非常高，则禁止执行。要了解更多信息，请参阅自动估算和执行阻止。

有关 estimate 的一般详细信息，请参阅内存估算。

以下将估算在写入模式下运行算法的内存要求：

MATCH (source:Station {name: 'Kings Cross'}), (target:Station {name: 'Kentish Town'})
CALL gds.shortestPath.astar.write.estimate('myGraph', {
    sourceNode: source,
    targetNode: target,
    latitudeProperty: 'latitude',
    longitudeProperty: 'longitude',
    writeRelationshipType: 'PATH'
})
YIELD nodeCount, relationshipCount, bytesMin, bytesMax, requiredMemory
RETURN nodeCount, relationshipCount, bytesMin, bytesMax, requiredMemory

表 10. 结果
nodeCount	relationshipCount	bytesMin	bytesMax	requiredMemory
5	5	1016	1016	"1016 字节"

流

在 stream 执行模式下，算法返回每个源-目标对的最短路径。这使我们能够直接检查结果或在 Cypher 中对其进行后处理，而不会产生任何副作用。

有关 stream 模式的更多详细信息，请参阅流。

以下将运行算法并流式传输结果：

MATCH (source:Station {name: 'Kings Cross'}), (target:Station {name: 'Kentish Town'})
CALL gds.shortestPath.astar.stream('myGraph', {
    sourceNode: source,
    targetNode: target,
    latitudeProperty: 'latitude',
    longitudeProperty: 'longitude',
    relationshipWeightProperty: 'distance'
})
YIELD index, sourceNode, targetNode, totalCost, nodeIds, costs, path
RETURN
    index,
    gds.util.asNode(sourceNode).name AS sourceNodeName,
    gds.util.asNode(targetNode).name AS targetNodeName,
    totalCost,
    [nodeId IN nodeIds | gds.util.asNode(nodeId).name] AS nodeNames,
    costs,
    nodes(path) as path
ORDER BY index

表 11. 结果
index	sourceNodeName	targetNodeName	totalCost	nodeNames	costs	path
0	"国王十字车站"	"肯蒂什镇"	3.3	["国王十字车站", "尤斯顿", "卡姆登镇", "肯蒂什镇"]	[0.0, 0.7, 2.0, 3.3]	[Node[0], Node[1], Node[2], Node[4]]

结果显示了图中 King’s Cross 节点和 Kentish Town 节点之间最短路径的总成本。它还显示了用于查找最短路径的节点 ID 的有序列表以及访问节点的累计成本。这可以在示例图中验证。Cypher Path 对象可以通过 path 返回字段返回。Path 对象包含节点对象和具有 cost 属性的虚拟关系。

变异

mutate 执行模式使用新关系更新命名图。每个新关系都表示从源节点到目标节点的路径。关系类型使用 mutateRelationshipType 选项进行配置。总路径成本使用 totalCost 属性存储。

当多个算法协同使用时，mutate 模式特别有用。

有关 mutate 模式的更多详细信息，请参阅变异。

以下将以 mutate 模式运行算法：

MATCH (source:Station {name: 'Kings Cross'}), (target:Station {name: 'Kentish Town'})
CALL gds.shortestPath.astar.mutate('myGraph', {
    sourceNode: source,
    targetNode: target,
    latitudeProperty: 'latitude',
    longitudeProperty: 'longitude',
    relationshipWeightProperty: 'distance',
    mutateRelationshipType: 'PATH'
})
YIELD relationshipsWritten
RETURN relationshipsWritten

表 12. 结果
relationshipsWritten
1

执行上述查询后，内存中的图将更新为类型为 PATH 的新关系。新关系将存储单个属性 totalCost。

生成的关系总是有向的，即使输入图是无向的。

写入

write 执行模式使用新关系更新 Neo4j 数据库。每个新关系代表从源节点到目标节点的路径。关系类型使用 writeRelationshipType 选项进行配置。总路径成本使用 totalCost 属性存储。中间节点 ID 使用 nodeIds 属性存储。到达中间节点的累计成本使用 costs 属性存储。

有关 write 模式的更多详细信息，请参阅写入。

以下将以 write 模式运行算法：

MATCH (source:Station {name: 'Kings Cross'}), (target:Station {name: 'Kentish Town'})
CALL gds.shortestPath.astar.write('myGraph', {
    sourceNode: source,
    targetNode: target,
    latitudeProperty: 'latitude',
    longitudeProperty: 'longitude',
    relationshipWeightProperty: 'distance',
    writeRelationshipType: 'PATH',
    writeNodeIds: true,
    writeCosts: true
})
YIELD relationshipsWritten
RETURN relationshipsWritten

表 13. 结果
relationshipsWritten
1

上述查询将把一个类型为 PATH 的关系写回 Neo4j。该关系存储三个描述路径的属性：totalCost、nodeIds 和 costs。

写入的关系总是有向的，即使输入图是无向的。