Creating Lists

How collect() works

collect() returns a list of elements. You can use collect() to create a list at any time during your query. When you create a list during a query, aggregation occurs.

Grouping key

During aggregation, the graph engine typically groups data based upon some value in a row. Here is a query where each row is returned by the name of the actor and the aggregation is done for each actor. The grouping key is a.name. That is, the non-aggregated value is the grouping key.

MATCH (a:Person)-[:ACTED_IN]->(m:Movie)
RETURN a.name AS Actor, collect(m.title) AS Movies LIMIT 100

Here is another example:

MATCH (actor:Person)-[:ACTED_IN]->(m:Movie)<-[:DIRECTED]-(director:Person)
RETURN actor.name AS Actor, director.name AS Director,
count(m) AS Collaborations, collect(m.title) AS Movies

In this example, both director.name and actor.name are grouping keys.

Using collect() examples

Here is an example where collect() is used to return aggregated data. Execute this query to see the query plan:

PROFILE
MATCH (m:Movie {title:'Jupiter Ascending'})
MATCH (d:Person)-[:DIRECTED]->(m)
MATCH (a:Person)-[:ACTED_IN]->(m)
RETURN m.title AS Title, collect(DISTINCT a.name) AS Actors,
collect(DISTINCT d.name) AS Directors

What you must remember is that each MATCH in a query returns rows that are operated on by the next step of the query.

In this query:

You can imagine that in a graph with many relationships, a query tuning goal should be to reduce the number of rows processed in the query (looking at the query plan). Even if you perform a single MATCH, you will see that the same query plan is used:

PROFILE
MATCH (d:Person)-[:DIRECTED]->(m:Movie {title:'Jupiter Ascending'})<-[:ACTED_IN]-(a:Person)
RETURN m.title AS Title, collect(DISTINCT a.name) AS Actors,
collect(DISTINCT d.name) AS Directors

To reduce the number of rows processed, we can move the aggregation up in the query as follows:

PROFILE
MATCH (m:Movie {title:'Jupiter Ascending'})
MATCH (d:Person)-[:DIRECTED]->(m)
WITH m, collect (d.name) AS Directors
MATCH (a:Person)-[:ACTED_IN]->(m)
RETURN m.title AS Title, collect(a.name) AS Actors, Directors

After the second MATCH we collect the row into a list. Notice that in the query plan the EagerAggregation operator executes. We pass on the Directors list, along with the Movie node for the next MATCH. Notice that in the query plan, only one row is passed into the third MATCH clause. We no longer need to use DISTINCT because there is no longer duplicate data in the rows.

In your query tuning, you should strive to reduce the number of rows processed during a query.

Collecting nodes

You can also collect nodes so that you may use the list of nodes for later processing in the query. Here is a query where we create Language nodes from data in the Movie nodes:

MATCH (m:Movie)
UNWIND m.languages AS language
WITH language, collect(m) AS movies
MERGE (l:Language {name:language})
WITH l, movies
UNWIND movies AS m
WITH l,m
MERGE (l)<-[:SPEAKS]-(m)
// NOTE: to undo these merges:
// MATCH (x:Language) DETACH DELETE x

Here you see in this code the following:

This code collects nodes using the language value so that each node can be used to create the relationship. In this type of query, you typically use collect() to collect nodes and UNWIND lists so they can be processed later in the query.

Collecting relationships

Here is an example where we collect relationships, then unwind them to query and return the correct values:

MATCH (u:User {name: "Misty Williams"})-[x]->()
WITH collect(x) AS ratings
UNWIND ratings AS r
WITH r WHERE r.rating <= 1
RETURN r.rating AS Rating, endNode(r).title AS Title

Notice here that we use endNode() to return the node at the end of the relationship.

Collecting paths in a query

Here is an example where we perform a query and use the nodes() function to return the list of all nodes in a path:

// Movies in all paths that begin with Elvis and end with an Actor that are 4 hops away from Elvis
MATCH path = (p:Person {name: 'Elvis Presley'})-[*4]-(a:Actor)
WITH nodes(path) AS n
UNWIND n AS x
WITH x WHERE x:Movie
RETURN DISTINCT x.title

In the above query, there is a mixture of Person and Movie nodes in the path. We specify a criteria x:Movie that we only want to return Movie nodes.

collect() vs. subquery

A subquery is a another way to aggregate data for later processing in your queries. Suppose we have this query which returns a list of at most three actors for every movie:

PROFILE MATCH (m:Movie)<-[:ACTED_IN]-(p)
WITH m, collect(p.name) AS Actors
WHERE size(Actors) <= 3
RETURN m.title AS Movie, Actors

This query returns 208 movies that have 3 or fewer actors.

The query can be rewritten as follows using a subquery:

PROFILE
CALL {
MATCH (m:Movie)<-[:ACTED_IN]-(p)
WITH  m , collect(p.name) as Actors
WHERE size(Actors)<= 3
RETURN  m.title as Movie, Actors
}
RETURN Movie, Actors

Both queries perform the same.