从遗留 Cypher 投影迁移到新版本

阅读指南

本指南旨在帮助那些一直使用旧版 Cypher 投影 gds.graph.project.cypher 的用户。现在，Cypher 投影通过 gds.graph.project 聚合函数来完成。我们假设用户对文中提到的操作和概念有一定了解，因此示例和比较部分力求简洁。详情请参阅 Cypher 投影文档。

结构性变化

旧版 Cypher 投影是一个独立的过程调用，其中 Cypher 查询作为字符串参数传递并由 GDS 执行。新的 Cypher 投影是一个作为 Cypher 查询一部分调用的聚合函数。GDS 不再负责或控制 Cypher 查询的执行。迁移到新的 Cypher 投影需要对 Cypher 查询的整体写法进行调整。

现在不再需要为节点和关系编写单独的查询。取而代之的是编写一个能够生成源节点和目标节点对的查询，并使用 gds.graph.project 将其聚合到图目录中。由于旧版 Cypher 投影的关系查询已经要求返回源节点和目标节点对，这可以作为新查询的一个很好的起点。大致来说，查询需要进行如下重写：

表 1. 两种 Cypher 投影之间的结构性差异
旧版 新增 
CALL gds.graph.project.cypher(
  $graphName,
  $nodeQuery,
  $relationshipQuery,
  $configuration
)
 
$relationshipQuery
RETURN gds.graph.project(
  $graphName,
  sourceNode,
  targetNode,
  $dataConfig,
  $configuration
)

查询不再需要遵循特定的结构，您可以使用任何能够生成源节点和目标节点对的 Cypher 查询。

语义变化

旧版 Cypher 投影对节点和关系有独立的查询。节点查询先执行，定义图中的所有节点。关系查询后执行，先前导入的节点作为关系的过滤器。只有在先前导入的节点之间的关系才会被导入图中。任何作为节点查询的一部分被导入，但未出现在任何关系中的节点，最终会在图中成为孤立节点。默认情况下，除非节点出现在关系中，否则所有节点都是孤立的。

新的 Cypher 投影没有独立的节点和关系查询。不再需要节点查询，节点会根据源节点和目标节点对隐式创建。如果需要在查询中显式创建孤立节点，可以通过提供 NULL 来代替目标节点来实现。默认情况下，除非显式设为孤立，否则所有节点都是连接的。

由于新的 Cypher 投影不再负责执行 Cypher 查询，因此图形配置不能再返回节点和关系查询。

示例

以下示例基于 旧版 Cypher 投影 和 新版 Cypher 投影 文档中列出的示例。

简单图

表 2. 两种 Cypher 投影的并排比较
旧版 新增

：带有潜在孤立节点的简单图投影

 
CALL gds.graph.project.cypher(
  'persons',
  'MATCH (n:Person) RETURN id(n) AS id',
  'MATCH (n:Person)-[r:KNOWS]->(m:Person) RETURN id(n) AS source, id(m) AS target')
YIELD
  graphName AS graph, nodeCount AS nodes, relationshipCount AS rels
 
MATCH (n:Person)
OPTIONAL MATCH (n)-[r:KNOWS]->(m:Person)
WITH gds.graph.project('persons', n, m) AS g
RETURN
  g.graphName AS graph, g.nodeCount AS node, g.relationshipCount AS rels

：不带孤立节点的简单图投影

不适用，旧版 Cypher 投影无法保证节点连接。

 
MATCH (n:Person)-[r:KNOWS]->(m:Person)
WITH gds.graph.project('persons', n, m) AS g
RETURN
  g.graphName AS graph, g.nodeCount AS node, g.relationshipCount AS rels

直接转换需要使用 OPTIONAL MATCH 子句来创建孤立节点，从而构建相同的图。这可能并非您最初想要的，但由于旧版 Cypher 投影无法保证连接的节点，因此这是必须的。通过使用与 $relationshipQuery 等效的内容，在新的 Cypher 投影中我们也只能得到连接的节点。

另一个区别是，我们将节点直接传递给新的 Cypher 投影。旧版 Cypher 投影要求我们传递节点 ID。通过直接传递节点，Cypher 投影能够识别投影的源是 Neo4j 数据库，这使得使用 .write 过程成为可能。也可以传递节点 ID 而不是节点 …​ gds.graph.project('persons', id(n), id(m))，但这仅在投影源不是 Neo4j 数据库时才建议使用。详见 任意源和目标 ID 值。

多重图

表 3. 两种 Cypher 投影的并排比较
旧版 新增

：多图投影

 
CALL gds.graph.project.cypher(
  'personsAndBooks',
  'MATCH (n) WHERE n:Person OR n:Book RETURN id(n) AS id, labels(n) AS labels',
  'MATCH (n)-[r:KNOWS|READ]->(m) RETURN id(n) AS source, id(m) AS target, type(r) AS type')
YIELD
  graphName AS graph, nodeQuery, nodeCount AS nodes, relationshipCount AS rels
 
MATCH (n)
WHERE n:Person OR n:Book
OPTIONAL MATCH (n)-[r:KNOWS|READ]->(m)
WHERE m:Person OR m:Book
WITH gds.graph.project(
  'personsAndBooks',
  n,
  m,
  {
    sourceNodeLabels: labels(n),
    targetNodeLabels: labels(m),
    relationshipType: type(r)
  }
) AS g
RETURN
  g.graphName AS graph, g.nodeCount AS node, g.relationshipCount AS rels

与上一个示例类似，我们必须使用 OPTIONAL MATCH 子句来创建孤立节点以生成相同的图。根据实际的图模式以及是否需要孤立节点，查询可能会有所不同。

节点标签和关系类型作为额外的配置映射传递给新的 Cypher 投影。节点标签需要作为 sourceNodeLabels 和 targetNodeLabels 传递，关系类型需要作为 relationshipType 传递。详见 多图。

节点属性

表 4. 两种 Cypher 投影的并排比较
旧版 新增

：带有节点属性的图投影

 
CALL gds.graph.project.cypher(
  'graphWithProperties',
  'MATCH (n:Person)
   RETURN
    id(n) AS id,
    labels(n) AS labels,
    n.age AS age',
  'MATCH (n)-[r:KNOWS]->(m) RETURN id(n) AS source, id(m) AS target, type(r) AS type'
)
YIELD
  graphName, nodeCount AS nodes, relationshipCount AS rels
RETURN graphName, nodes, rels
 
MATCH (n:Person)
OPTIONAL MATCH (n)-[r:KNOWS]->(m:Person)
WITH gds.graph.project(
  'graphWithProperties',
  n,
  m,
  {
    sourceNodeLabels: labels(n),
    targetNodeLabels: labels(m),
    sourceNodeProperties: n { .age },
    targetNodeProperties: m { .age },
    relationshipType: type(r)
  }
) AS g
RETURN
  g.graphName AS graph, g.nodeCount AS node, g.relationshipCount AS rels

：带有可选节点属性的图投影

 
CALL gds.graph.project.cypher(
  'graphWithProperties',
  'MATCH (n)
   WHERE n:Book OR n:Person
   RETURN
    id(n) AS id,
    labels(n) AS labels,
    coalesce(n.age, 18) AS age',
    coalesce(n.price, 5.0) AS price,
    n.ratings AS ratings',
  'MATCH (n)-[r:KNOWS|READ]->(m) RETURN id(n) AS source, id(m) AS target, type(r) AS type'
)
YIELD
  graphName, nodeCount AS nodes, relationshipCount AS rels
RETURN graphName, nodes, rels
 
MATCH (n)
WHERE n:Person OR n:Book
OPTIONAL MATCH (n)-[r:KNOWS|READ]->(m)
WHERE m:Person OR m:Book
WITH gds.graph.project(
  'graphWithProperties',
  n,
  m,
  {
    sourceNodeLabels: labels(n),
    targetNodeLabels: labels(m),
    sourceNodeProperties: n { age: coalesce(n.age, 18), price: coalesce(n.price, 5.0), .ratings },
    targetNodeProperties: n { age: coalesce(n.age, 18), price: coalesce(n.price, 5.0), .ratings },
    relationshipType: type(r)
  }
) AS g
RETURN
  g.graphName AS graph, g.nodeCount AS node, g.relationshipCount AS rels

与上一个示例类似，我们在额外的映射中传递标签和属性。我们可以使用映射投影以及任何其他 Cypher 表达式来创建属性。详见 节点属性。

关系属性

表 5. 两种 Cypher 投影的并排比较
旧版 新增

：带有关系属性的图投影

 
CALL gds.graph.project.cypher(
  'readWithProperties',
  'MATCH (n) RETURN id(n) AS id',
  'MATCH (n)-[r:READ]->(m)
    RETURN id(n) AS source, id(m) AS target, r.numberOfPages AS numberOfPages'
)
YIELD
  graphName AS graph, nodeCount AS nodes, relationshipCount AS rels
 
MATCH (n)-[r:READ]->(m)
WITH gds.graph.project(
  'readWithProperties',
  n,
  m,
  { relationshipProperties: r { .numberOfPages } }
) AS g
RETURN
  g.graphName AS graph, g.nodeCount AS nodes, g.relationshipCount AS rels

与上一个示例类似，我们在额外的映射中传递属性，这里使用 relationshipProperties 键。我们可以使用映射投影以及任何其他 Cypher 表达式来创建属性。详见 关系属性。

平行关系

表 6. 两种 Cypher 投影的并排比较
旧版 新增

：带有平行关系的图投影

 
CALL gds.graph.project.cypher(
  'readCount',
  'MATCH (n) RETURN id(n) AS id',
  'MATCH (n)-[r:READ]->(m)
    RETURN id(n) AS source, id(m) AS target, type(r) AS type, count(r) AS numberOfReads'
)
YIELD
  graphName AS graph, nodeCount AS nodes, relationshipCount AS rels
 
MATCH (n)-[r:READ]->(m)
WITH n, m, count(r) AS numberOfReads
WITH gds.graph.project(
  'readCount',
  n,
  m,
  {
    relationshipProperties: { numberOfReads: numberOfReads }
  }
) AS g
RETURN
  g.graphName AS graph, g.nodeCount AS nodes, g.relationshipCount AS rels

：带有平行关系和关系属性的图投影

 
CALL gds.graph.project.cypher(
  'readSums',
  'MATCH (n) RETURN id(n) AS id',
  'MATCH (n)-[r:READ]->(m)
    RETURN id(n) AS source, id(m) AS target, sum(r.numberOfPages) AS numberOfPages'
)
YIELD
  graphName AS graph, nodeCount AS nodes, relationshipCount AS rels
 
MATCH (n)-[r:READ]->(m)
WITH n, m, sum(r.numberOfPages) AS numberOfPages
WITH gds.graph.project(
  'readSums',
  n,
  m,
  {
    relationshipProperties: { numberOfPages: numberOfPages }
  }
) AS g
RETURN
  g.graphName AS graph, g.nodeCount AS nodes, g.relationshipCount AS rels

与旧版 Cypher 投影类似，没有机制可以让 GDS 自动聚合平行关系。对平行关系的聚合可以在查询中使用任何适合图模式和数据的方法来完成。详见 平行关系。

投影过滤后的图

表 7. 两种 Cypher 投影的并排比较
旧版 新增

：带有过滤图的图投影

 
CALL gds.graph.project.cypher(
  'existingNumberOfPages',
  'MATCH (n) RETURN id(n) AS id',
  'MATCH (n)-[r:READ]->(m)
    WHERE r.numberOfPages IS NOT NULL
    RETURN id(n) AS source, id(m) AS target, r.numberOfPages AS numberOfPages'
)
YIELD
  graphName AS graph, nodeCount AS nodes, relationshipCount AS rels
 
MATCH (n) OPTIONAL MATCH (n)-[r:READ]->(m)
WHERE r.numberOfPages IS NOT NULL
WITH gds.graph.project('existingNumberOfPages', n, m, { relationshipProperties: r { .numberOfPages } }) AS g
RETURN
  g.graphName AS graph, g.nodeCount AS nodes, g.relationshipCount AS rels

与旧版 Cypher 投影类似，我们可以在传递给 Cypher 投影之前使用任何 Cypher 过滤方法。详见 投影过滤后的 Neo4j 图。

投影无向图

表 8. 两种 Cypher 投影的并排比较
旧版 新增

：带有无向图的图投影

不适用，旧版 Cypher 投影无法投影无向图。

 
MATCH (n)-[r:KNOWS|READ]->(m)
WHERE n:Book OR n:Person
WITH gds.graph.project(
  'graphWithUndirectedRelationships',
  source,
  target,
  {},
  {undirectedRelationshipTypes: ['*']}
) AS g
RETURN g.graphName AS graph, g.nodeCount AS nodes, g.relationshipCount AS rels

新的 Cypher 投影可以投影无向图。详见 无向关系。

内存估算

表 9. 两种 Cypher 投影的并排比较
旧版 新增

：投影图的内存估算

 
CALL gds.graph.project.cypher.estimate(
  'MATCH (n:Person) RETURN id(n) AS id',
  'MATCH (n:Person)-[r:KNOWS]->(m:Person) RETURN id(n) AS source, id(m) AS target'
) YIELD requiredMemory, bytesMin, bytesMax
 
MATCH (n:Person)-[r:KNOWS]-(m)
WITH count(n) AS nodeCount, count(r) AS relationshipCount
CALL gds.graph.project.estimate('*', '*', {
  nodeCount: nodeCount,
  relationshipCount: relationshipCount,
})
YIELD requiredMemory, bytesMin, bytesMax

由于新的 Cypher 投影不再是一个过程，因此也没有 .estimate 方法。取而代之的是，我们可以使用 gds.graph.project.estimate 过程 来估算图投影的内存需求。