Scoping Variables

Using WITH to redefine scope

Let’s look at scoping variables in more detail. Suppose we have this query:

WITH  'toy story' AS mt, 'Tom Hanks' AS actorName
MATCH (p:Person)-[:ACTED_IN]->(m:Movie)
WHERE p.name = actorName
AND toLower(m.title) CONTAINS mt
RETURN m.title AS movies

For this query, mt and actorName are within scope of the MATCH clause that also uses the WHERE clause. It retrieves the Person node, then all the movies that Tom Hanks acted in, then it filters and returns the movies that contain mt.

Now, let’s look at this query:

WITH  'toy story' AS mt, 'Tom Hanks' AS actorName
MATCH (p:Person)-[:ACTED_IN]->(m:Movie)
WITH m, toLower(m.title) AS movieTitle
WHERE p.name = actorName
AND movieTitle CONTAINS mt
RETURN m.title AS movies, movieTitle

The variables mt, and actorName are available to the MATCH clause and the WHERE clause just like the previous query. What is different here, however, is that we must add the m to the second WITH clause so that the node can be used to return the title of the node. A WITH clause is used to define or redefine the scope of variables. Because we want to redefine what is used for the WHERE clause, we add a new WITH clause. This creates a new scope for the remainder of the query so that m and movieTitle can be used to return values. If you were to remove the m in the second WITH clause, the query would not compile.

Notice also that you can define expressions using WITH. When you define an expression (for example, toLower(m.title), you must specify an alias defined with the AS keyword.

Limiting results

Suppose we have this query where we want to return only two rows:

WITH  'Tom Hanks' AS theActor
MATCH (p:Person)-[:ACTED_IN]->(m:Movie)
WHERE p.name = theActor
RETURN m.title AS movies LIMIT 2

Another way to write this query is:

WITH  'Tom Hanks' AS theActor
MATCH (p:Person)-[:ACTED_IN]->(m:Movie)
WHERE p.name = theActor
WITH m  LIMIT 2
// possibly do more with the two m nodes
RETURN m.title AS movies

With this query, two Movie nodes are retrieved. What is different here is that you can use WITH to limit how many m nodes are used later in the query. Passing nodes on to the next MATCH clause is called pipelining that you will learn about in the next lesson.

Ordering results

If you are limiting the nodes to process further on in the query or for the RETURN clause, you can also order them:

WITH  'Tom Hanks' AS theActor
MATCH (p:Person)-[:ACTED_IN]->(m:Movie)
WHERE p.name = theActor
WITH m ORDER BY m.year LIMIT 5
// possibly do more with the five m nodes in a particular order
RETURN m.title AS movies, m.year AS yearReleased

Using map projections in a WITH clause

Here is another example where we want to customize the properties of nodes that are returned. Using a map projection, you can specify which properties are returned. This type of customization of nodes returned is very useful when you are integrating with an application.

MATCH (n:Movie)
WHERE n.imdbRating IS NOT NULL
AND n.poster IS NOT NULL
WITH n {
  .title,
  .year,
  .languages,
  .plot,
  .poster,
  .imdbRating,
  directors: [ (n)<-[:DIRECTED]-(d) | d { tmdbId:d.imdbId, .name } ]
}
ORDER BY n.imdbRating DESC LIMIT 4
RETURN collect(n)

This query returns a subset of the data in a Movie node. It returns the top four rated movies. Because we have specified a limit of four, only 4 objects with the specified properties are added to the list. This type of data returned is commonly used by GraphQL and JavaScript applications.