Migration from Alpha Cypher Aggregation to new Cypher projection

Who should read this guide

This guide is intended for users who have been using the Alpha Cypher Aggregation gds.alpha.graph.project. Cypher projections are now done using the gds.graph.project aggregation function. We assume that most of the mentioned operations and concepts can be understood with little explanation. Thus we are intentionally brief in the examples and comparisons. Please see the documentation for the Cypher projection for more details.

API Changes

The new Cypher projection is a replacement for the Alpha Cypher Aggregation. Like the Alpha Cypher Aggregation, the new Cypher projection is an aggregation function that is called as part of a Cypher query.

The following changes have been made to the API:

  • The new Cypher projection is called using gds.graph.project instead of gds.alpha.graph.project.

  • The new Cypher projection defines a single map parameter for defining projection related information such as labels or properties.

    • There is still a separate map parameter for defining the graph configuration.

  • The properties key of the relationship configuration map has been renamed to relationshipProperties.

  • Additional validation to reduce mis-use of the API:

    • Validate that each sourceNode* entry has a corresponding targetNode* entry and vice-versa.

    • Identify end help with migration to this new API if any of the points above have not been followed.

Table 1. Structural changes between the Alpha aggregation/new projections:
Legacy New 
$query
RETURN gds.alpha.graph.project(
  $graphName,
  sourceNode,
  targetNode,
  $nodeConfig,
  $relationshipConfig,
  $configuration
)
 
$relationshipQuery
RETURN gds.graph.project(
  $graphName,
  sourceNode,
  targetNode,
  $dataConfig,
  $configuration
)

Examples

The following examples not include the full Cypher queries before the aggreation function is called, nor do they include and YIELD of return fields. There are no changes related to those two aspects.

Table 2. Side-by-side comparison
Alpha New

: Projection without any configuration

 
...
RETURN gds.alpha.graph.project('g', source, target)
 
...
RETURN gds.graph.project('g', source, target)

: Multi-graph projection

 
...
RETURN gds.alpha.graph.project(
  'g',
  source,
  target,
  {
    sourceNodeLabels: labels(source),
    targetNodeLabels: labels(target),
  }, {
    relationshipType: type(r)
  }
)
 
...
RETURN gds.graph.project(
  'g',
  source,
  target,
  {
    sourceNodeLabels: labels(source),
    targetNodeLabels: labels(target),
    relationshipType: type(rel)
  }
)

: Graph projection with properties

 
...
RETURN gds.alpha.graph.project(
  'g',
  source,
  target,
  {
    sourceNodeLabels: labels(source),
    targetNodeLabels: labels(target),
    sourceNodeProperties: source { .age },
    targetNodeProperties: target { .age },
  }, {
    relationshipType: type(rel),
    properties: rel { .numberOfPages }
  }
)
 
...
RETURN gds.graph.project(
  'g',
  source,
  target,
  {
    sourceNodeLabels: labels(source),
    targetNodeLabels: labels(target),
    sourceNodeProperties: source { .age },
    targetNodeProperties: target { .age },
    relationshipType: type(rel),
    relationshipProperties: rel { .numberOfPages }
  }
)

: Graph projection with one-sided properties

 
...
RETURN gds.alpha.graph.project(
  'g',
  source,
  target,
  {
    sourceNodeLabels: labels(source),
    sourceNodeProperties: source { .age },
  }
)
 
...
RETURN gds.graph.project(
  'g',
  source,
  target,
  {
    sourceNodeLabels: labels(source),
    targetNodeLabels: NULL,
    sourceNodeProperties: source { .age },
    targetNodeProperties: NULL,
  }
)