Cypher Projections

Syntax

To create a Cypher project you define a Cypher query and use the gds.graph.project aggregation function to create the projection.

MATCH (sourceNode:Node)-[r:RELATIONSHIP]->(targetNode:Node)
WITH gds.graph.project(
    graphName: String,
    sourceNode: Node or Integer,
    targetNode: Node or Integer,
    dataConfig: Map,
    configuration: Map
) AS g
RETURN g

A Cypher projection takes two mandatory arguments: graphName and sourceNode. For many use cases, you would also define a targetNode. In addition, the optional configuration parameter allows us to further configure graph creation.

Applied Example

In the last lesson we answered which actors were most prolific based on the number of movies they acted in. Suppose instead we wanted to know which actors are the most influential in terms of the number of other actors they have been in recent, high grossing, movies with.

For the sake of this example, we will call a movie “recent” if it was released on or after 1990, and high-grossing if it had revenue >= $1M.

The graph is not set up to answer this question well with a direct native projection. However, we can use a cypher projection to filter to the appropriate nodes and perform an aggregation to create an ACTED_WITH relationship that has a actedWithCount property going directly between actor nodes.

The Cypher query to create this data set would be:

MATCH (source:Actor)-[r:ACTED_IN]->(m:Movie)<-[:ACTED_IN]-(target)
WHERE m.year >= 1990 AND m.revenue >= 1000000
RETURN source.name, count(r) as actedWithCount

The actor’s name and the count of movies they acted in with other actors in recent, high-grossing movies are returned.

You can use this query to create a Cypher projection.

MATCH (source:Actor)-[r:ACTED_IN]->(m:Movie)<-[:ACTED_IN]-(target)
WHERE m.year >= 1990 AND m.revenue >= 1000000
WITH source, target, count(r) as actedWithCount
WITH gds.graph.project(
    'cypher-proj',
    source,
    target,
    { relationshipProperties:
        {
            actedWithCount: actedWithCount
        }
    }
) AS g
RETURN
  g.graphName AS graph, g.nodeCount AS nodes, g.relationshipCount AS rels

Note how the source and target nodes are included as parameters. The actedWithCount property is included in the relationshipProperties in the dataConfig parameter.

Once the projection is created we can apply degree centrality like we did last lesson. Except we will weight the degree centrality by actedWithCount property and also directly stream the top 10 results back. This counts how many times the actor has acted with other actors in recent, high grossing movies.

CALL gds.degree.stream('cypher-proj',{relationshipWeightProperty: 'actedWithCount'})
YIELD nodeId, score
RETURN gds.util.asNode(nodeId).name AS name, score
ORDER BY score DESC LIMIT 10

The results include some big name actors as we would expect.

Flexibility of Cypher Projections

In the above example, there were two things that prevented us from directly using a native projection. They also happen to be two of the most common cases for using Cypher Projections.

Further options enabled by Cypher projections include merging different node labels and relationship types and defining virtual relationships between nodes based on property conditions or other query logic.

Check your understanding