2.11. Lists

Cypher has comprehensive support for lists.

Information regarding operators such as list concatenation (+), element existence checking (IN) and access ([]) can be found here. The behavior of the IN and [] operators with respect to null is detailed here.

2.11.1. Lists in general

A literal list is created by using brackets and separating the elements in the list with commas.

Query. 

RETURN [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] AS list

Table 2.57. Result
list

1 row

[0,1,2,3,4,5,6,7,8,9]

Try this query live.  CREATE (keanu:Person {name: 'Keanu Reeves'}), (johnnymnemonic:Movie {title: 'Johnny Mnemonic', released: 1995}), (somethingsgottagive:Movie {title: 'Somethings Gotta Give', released: 2003}), (thematrixrevolutions:Movie {title: 'The Matrix Revolutions', released: 2003}), (thematrixreloaded:Movie {title: 'The Matrix Reloaded', released: 2003}), (thereplacements:Movie {title: 'The Replacements', released: 2000}), (thematrix:Movie {title: 'The Matrix', released: 1999}), (thedevilsadvocate:Movie {title: 'The Devils Advocate', released: 1997}), (keanu)-[:ACTED_IN]->(johnnymnemonic), (keanu)-[:ACTED_IN]->(somethingsgottagive), (keanu)-[:ACTED_IN]->(thematrixrevolutions), (keanu)-[:ACTED_IN]->(thematrixreloaded), (keanu)-[:ACTED_IN]->(thereplacements), (keanu)-[:ACTED_IN]->(thematrix), (keanu)-[:ACTED_IN]->(thedevilsadvocate) RETURN [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] AS list

In our examples, we’ll use the range function. It gives you a list containing all numbers between given start and end numbers. Range is inclusive in both ends.

To access individual elements in the list, we use the square brackets again. This will extract from the start index and up to but not including the end index.

Query. 

RETURN range(0, 10)[3]

Table 2.58. Result
range(0, 10)[3]

1 row

3

Try this query live.  CREATE (keanu:Person {name: 'Keanu Reeves'}), (johnnymnemonic:Movie {title: 'Johnny Mnemonic', released: 1995}), (somethingsgottagive:Movie {title: 'Somethings Gotta Give', released: 2003}), (thematrixrevolutions:Movie {title: 'The Matrix Revolutions', released: 2003}), (thematrixreloaded:Movie {title: 'The Matrix Reloaded', released: 2003}), (thereplacements:Movie {title: 'The Replacements', released: 2000}), (thematrix:Movie {title: 'The Matrix', released: 1999}), (thedevilsadvocate:Movie {title: 'The Devils Advocate', released: 1997}), (keanu)-[:ACTED_IN]->(johnnymnemonic), (keanu)-[:ACTED_IN]->(somethingsgottagive), (keanu)-[:ACTED_IN]->(thematrixrevolutions), (keanu)-[:ACTED_IN]->(thematrixreloaded), (keanu)-[:ACTED_IN]->(thereplacements), (keanu)-[:ACTED_IN]->(thematrix), (keanu)-[:ACTED_IN]->(thedevilsadvocate) RETURN range(0, 10)[3]

You can also use negative numbers, to start from the end of the list instead.

Query. 

RETURN range(0, 10)[-3]

Table 2.59. Result
range(0, 10)[-3]

1 row

8

Try this query live.  CREATE (keanu:Person {name: 'Keanu Reeves'}), (johnnymnemonic:Movie {title: 'Johnny Mnemonic', released: 1995}), (somethingsgottagive:Movie {title: 'Somethings Gotta Give', released: 2003}), (thematrixrevolutions:Movie {title: 'The Matrix Revolutions', released: 2003}), (thematrixreloaded:Movie {title: 'The Matrix Reloaded', released: 2003}), (thereplacements:Movie {title: 'The Replacements', released: 2000}), (thematrix:Movie {title: 'The Matrix', released: 1999}), (thedevilsadvocate:Movie {title: 'The Devils Advocate', released: 1997}), (keanu)-[:ACTED_IN]->(johnnymnemonic), (keanu)-[:ACTED_IN]->(somethingsgottagive), (keanu)-[:ACTED_IN]->(thematrixrevolutions), (keanu)-[:ACTED_IN]->(thematrixreloaded), (keanu)-[:ACTED_IN]->(thereplacements), (keanu)-[:ACTED_IN]->(thematrix), (keanu)-[:ACTED_IN]->(thedevilsadvocate) RETURN range(0, 10)[-3]

Finally, you can use ranges inside the brackets to return ranges of the list.

Query. 

RETURN range(0, 10)[0..3]

Table 2.60. Result
range(0, 10)[0..3]

1 row

[0,1,2]

Try this query live.  CREATE (keanu:Person {name: 'Keanu Reeves'}), (johnnymnemonic:Movie {title: 'Johnny Mnemonic', released: 1995}), (somethingsgottagive:Movie {title: 'Somethings Gotta Give', released: 2003}), (thematrixrevolutions:Movie {title: 'The Matrix Revolutions', released: 2003}), (thematrixreloaded:Movie {title: 'The Matrix Reloaded', released: 2003}), (thereplacements:Movie {title: 'The Replacements', released: 2000}), (thematrix:Movie {title: 'The Matrix', released: 1999}), (thedevilsadvocate:Movie {title: 'The Devils Advocate', released: 1997}), (keanu)-[:ACTED_IN]->(johnnymnemonic), (keanu)-[:ACTED_IN]->(somethingsgottagive), (keanu)-[:ACTED_IN]->(thematrixrevolutions), (keanu)-[:ACTED_IN]->(thematrixreloaded), (keanu)-[:ACTED_IN]->(thereplacements), (keanu)-[:ACTED_IN]->(thematrix), (keanu)-[:ACTED_IN]->(thedevilsadvocate) RETURN range(0, 10)[0..3]

Query. 

RETURN range(0, 10)[0..-5]

Table 2.61. Result
range(0, 10)[0..-5]

1 row

[0,1,2,3,4,5]

Try this query live.  CREATE (keanu:Person {name: 'Keanu Reeves'}), (johnnymnemonic:Movie {title: 'Johnny Mnemonic', released: 1995}), (somethingsgottagive:Movie {title: 'Somethings Gotta Give', released: 2003}), (thematrixrevolutions:Movie {title: 'The Matrix Revolutions', released: 2003}), (thematrixreloaded:Movie {title: 'The Matrix Reloaded', released: 2003}), (thereplacements:Movie {title: 'The Replacements', released: 2000}), (thematrix:Movie {title: 'The Matrix', released: 1999}), (thedevilsadvocate:Movie {title: 'The Devils Advocate', released: 1997}), (keanu)-[:ACTED_IN]->(johnnymnemonic), (keanu)-[:ACTED_IN]->(somethingsgottagive), (keanu)-[:ACTED_IN]->(thematrixrevolutions), (keanu)-[:ACTED_IN]->(thematrixreloaded), (keanu)-[:ACTED_IN]->(thereplacements), (keanu)-[:ACTED_IN]->(thematrix), (keanu)-[:ACTED_IN]->(thedevilsadvocate) RETURN range(0, 10)[0..-5]

Query. 

RETURN range(0, 10)[-5..]

Table 2.62. Result
range(0, 10)[-5..]

1 row

[6,7,8,9,10]

Try this query live.  CREATE (keanu:Person {name: 'Keanu Reeves'}), (johnnymnemonic:Movie {title: 'Johnny Mnemonic', released: 1995}), (somethingsgottagive:Movie {title: 'Somethings Gotta Give', released: 2003}), (thematrixrevolutions:Movie {title: 'The Matrix Revolutions', released: 2003}), (thematrixreloaded:Movie {title: 'The Matrix Reloaded', released: 2003}), (thereplacements:Movie {title: 'The Replacements', released: 2000}), (thematrix:Movie {title: 'The Matrix', released: 1999}), (thedevilsadvocate:Movie {title: 'The Devils Advocate', released: 1997}), (keanu)-[:ACTED_IN]->(johnnymnemonic), (keanu)-[:ACTED_IN]->(somethingsgottagive), (keanu)-[:ACTED_IN]->(thematrixrevolutions), (keanu)-[:ACTED_IN]->(thematrixreloaded), (keanu)-[:ACTED_IN]->(thereplacements), (keanu)-[:ACTED_IN]->(thematrix), (keanu)-[:ACTED_IN]->(thedevilsadvocate) RETURN range(0, 10)[-5..]

Query. 

RETURN range(0, 10)[..4]

Table 2.63. Result
range(0, 10)[..4]

1 row

[0,1,2,3]

Try this query live.  CREATE (keanu:Person {name: 'Keanu Reeves'}), (johnnymnemonic:Movie {title: 'Johnny Mnemonic', released: 1995}), (somethingsgottagive:Movie {title: 'Somethings Gotta Give', released: 2003}), (thematrixrevolutions:Movie {title: 'The Matrix Revolutions', released: 2003}), (thematrixreloaded:Movie {title: 'The Matrix Reloaded', released: 2003}), (thereplacements:Movie {title: 'The Replacements', released: 2000}), (thematrix:Movie {title: 'The Matrix', released: 1999}), (thedevilsadvocate:Movie {title: 'The Devils Advocate', released: 1997}), (keanu)-[:ACTED_IN]->(johnnymnemonic), (keanu)-[:ACTED_IN]->(somethingsgottagive), (keanu)-[:ACTED_IN]->(thematrixrevolutions), (keanu)-[:ACTED_IN]->(thematrixreloaded), (keanu)-[:ACTED_IN]->(thereplacements), (keanu)-[:ACTED_IN]->(thematrix), (keanu)-[:ACTED_IN]->(thedevilsadvocate) RETURN range(0, 10)[..4]

Out-of-bound slices are simply truncated, but out-of-bound single elements return null.

Query. 

RETURN range(0, 10)[15]

Table 2.64. Result
range(0, 10)[15]

1 row

<null>

Try this query live.  CREATE (keanu:Person {name: 'Keanu Reeves'}), (johnnymnemonic:Movie {title: 'Johnny Mnemonic', released: 1995}), (somethingsgottagive:Movie {title: 'Somethings Gotta Give', released: 2003}), (thematrixrevolutions:Movie {title: 'The Matrix Revolutions', released: 2003}), (thematrixreloaded:Movie {title: 'The Matrix Reloaded', released: 2003}), (thereplacements:Movie {title: 'The Replacements', released: 2000}), (thematrix:Movie {title: 'The Matrix', released: 1999}), (thedevilsadvocate:Movie {title: 'The Devils Advocate', released: 1997}), (keanu)-[:ACTED_IN]->(johnnymnemonic), (keanu)-[:ACTED_IN]->(somethingsgottagive), (keanu)-[:ACTED_IN]->(thematrixrevolutions), (keanu)-[:ACTED_IN]->(thematrixreloaded), (keanu)-[:ACTED_IN]->(thereplacements), (keanu)-[:ACTED_IN]->(thematrix), (keanu)-[:ACTED_IN]->(thedevilsadvocate) RETURN range(0, 10)[15]

Query. 

RETURN range(0, 10)[5..15]

Table 2.65. Result
range(0, 10)[5..15]

1 row

[5,6,7,8,9,10]

Try this query live.  CREATE (keanu:Person {name: 'Keanu Reeves'}), (johnnymnemonic:Movie {title: 'Johnny Mnemonic', released: 1995}), (somethingsgottagive:Movie {title: 'Somethings Gotta Give', released: 2003}), (thematrixrevolutions:Movie {title: 'The Matrix Revolutions', released: 2003}), (thematrixreloaded:Movie {title: 'The Matrix Reloaded', released: 2003}), (thereplacements:Movie {title: 'The Replacements', released: 2000}), (thematrix:Movie {title: 'The Matrix', released: 1999}), (thedevilsadvocate:Movie {title: 'The Devils Advocate', released: 1997}), (keanu)-[:ACTED_IN]->(johnnymnemonic), (keanu)-[:ACTED_IN]->(somethingsgottagive), (keanu)-[:ACTED_IN]->(thematrixrevolutions), (keanu)-[:ACTED_IN]->(thematrixreloaded), (keanu)-[:ACTED_IN]->(thereplacements), (keanu)-[:ACTED_IN]->(thematrix), (keanu)-[:ACTED_IN]->(thedevilsadvocate) RETURN range(0, 10)[5..15]

You can get the size of a list as follows:

Query. 

RETURN size(range(0, 10)[0..3])

Table 2.66. Result
size(range(0, 10)[0..3])

1 row

3

Try this query live.  CREATE (keanu:Person {name: 'Keanu Reeves'}), (johnnymnemonic:Movie {title: 'Johnny Mnemonic', released: 1995}), (somethingsgottagive:Movie {title: 'Somethings Gotta Give', released: 2003}), (thematrixrevolutions:Movie {title: 'The Matrix Revolutions', released: 2003}), (thematrixreloaded:Movie {title: 'The Matrix Reloaded', released: 2003}), (thereplacements:Movie {title: 'The Replacements', released: 2000}), (thematrix:Movie {title: 'The Matrix', released: 1999}), (thedevilsadvocate:Movie {title: 'The Devils Advocate', released: 1997}), (keanu)-[:ACTED_IN]->(johnnymnemonic), (keanu)-[:ACTED_IN]->(somethingsgottagive), (keanu)-[:ACTED_IN]->(thematrixrevolutions), (keanu)-[:ACTED_IN]->(thematrixreloaded), (keanu)-[:ACTED_IN]->(thereplacements), (keanu)-[:ACTED_IN]->(thematrix), (keanu)-[:ACTED_IN]->(thedevilsadvocate) RETURN size(range(0, 10)[0..3])

2.11.2. List comprehension

List comprehension is a syntactic construct available in Cypher for creating a list based on existing lists. It follows the form of the mathematical set-builder notation (set comprehension) instead of the use of map and filter functions.

Query. 

RETURN [x IN range(0,10) WHERE x % 2 = 0 | x^3] AS result

Table 2.67. Result
result

1 row

[0.0,8.0,64.0,216.0,512.0,1000.0]

Try this query live.  CREATE (keanu:Person {name: 'Keanu Reeves'}), (johnnymnemonic:Movie {title: 'Johnny Mnemonic', released: 1995}), (somethingsgottagive:Movie {title: 'Somethings Gotta Give', released: 2003}), (thematrixrevolutions:Movie {title: 'The Matrix Revolutions', released: 2003}), (thematrixreloaded:Movie {title: 'The Matrix Reloaded', released: 2003}), (thereplacements:Movie {title: 'The Replacements', released: 2000}), (thematrix:Movie {title: 'The Matrix', released: 1999}), (thedevilsadvocate:Movie {title: 'The Devils Advocate', released: 1997}), (keanu)-[:ACTED_IN]->(johnnymnemonic), (keanu)-[:ACTED_IN]->(somethingsgottagive), (keanu)-[:ACTED_IN]->(thematrixrevolutions), (keanu)-[:ACTED_IN]->(thematrixreloaded), (keanu)-[:ACTED_IN]->(thereplacements), (keanu)-[:ACTED_IN]->(thematrix), (keanu)-[:ACTED_IN]->(thedevilsadvocate) RETURN [x IN range(0,10) WHERE x % 2 = 0 | x^3 ] AS result

Either the WHERE part, or the expression, can be omitted, if you only want to filter or map respectively.

Query. 

RETURN [x IN range(0,10) WHERE x % 2 = 0] AS result

Table 2.68. Result
result

1 row

[0,2,4,6,8,10]

Try this query live.  CREATE (keanu:Person {name: 'Keanu Reeves'}), (johnnymnemonic:Movie {title: 'Johnny Mnemonic', released: 1995}), (somethingsgottagive:Movie {title: 'Somethings Gotta Give', released: 2003}), (thematrixrevolutions:Movie {title: 'The Matrix Revolutions', released: 2003}), (thematrixreloaded:Movie {title: 'The Matrix Reloaded', released: 2003}), (thereplacements:Movie {title: 'The Replacements', released: 2000}), (thematrix:Movie {title: 'The Matrix', released: 1999}), (thedevilsadvocate:Movie {title: 'The Devils Advocate', released: 1997}), (keanu)-[:ACTED_IN]->(johnnymnemonic), (keanu)-[:ACTED_IN]->(somethingsgottagive), (keanu)-[:ACTED_IN]->(thematrixrevolutions), (keanu)-[:ACTED_IN]->(thematrixreloaded), (keanu)-[:ACTED_IN]->(thereplacements), (keanu)-[:ACTED_IN]->(thematrix), (keanu)-[:ACTED_IN]->(thedevilsadvocate) RETURN [x IN range(0,10) WHERE x % 2 = 0 ] AS result

Query. 

RETURN [x IN range(0,10)| x^3] AS result

Table 2.69. Result
result

1 row

[0.0,1.0,8.0,27.0,64.0,125.0,216.0,343.0,512.0,729.0,1000.0]

Try this query live.  CREATE (keanu:Person {name: 'Keanu Reeves'}), (johnnymnemonic:Movie {title: 'Johnny Mnemonic', released: 1995}), (somethingsgottagive:Movie {title: 'Somethings Gotta Give', released: 2003}), (thematrixrevolutions:Movie {title: 'The Matrix Revolutions', released: 2003}), (thematrixreloaded:Movie {title: 'The Matrix Reloaded', released: 2003}), (thereplacements:Movie {title: 'The Replacements', released: 2000}), (thematrix:Movie {title: 'The Matrix', released: 1999}), (thedevilsadvocate:Movie {title: 'The Devils Advocate', released: 1997}), (keanu)-[:ACTED_IN]->(johnnymnemonic), (keanu)-[:ACTED_IN]->(somethingsgottagive), (keanu)-[:ACTED_IN]->(thematrixrevolutions), (keanu)-[:ACTED_IN]->(thematrixreloaded), (keanu)-[:ACTED_IN]->(thereplacements), (keanu)-[:ACTED_IN]->(thematrix), (keanu)-[:ACTED_IN]->(thedevilsadvocate) RETURN [x IN range(0,10) | x^3 ] AS result

2.11.3. Pattern comprehension

Pattern comprehension is a syntactic construct available in Cypher for creating a list based on matchings of a pattern. A pattern comprehension will match the specified pattern just like a normal MATCH clause, with predicates just like a normal WHERE clause, but will yield a custom projection as specified.

The following graph is used for the example below:

Figure 2.3. Graph
alt

Query. 

MATCH (a:Person { name: 'Keanu Reeves' })
RETURN [(a)-->(b) WHERE b:Movie | b.released] AS years

Table 2.70. Result
years

1 row

[1997,2003,2003,2000,1999,2003,1995]

Try this query live.  CREATE (keanu:Person {name: 'Keanu Reeves'}), (johnnymnemonic:Movie {title: 'Johnny Mnemonic', released: 1995}), (somethingsgottagive:Movie {title: 'Somethings Gotta Give', released: 2003}), (thematrixrevolutions:Movie {title: 'The Matrix Revolutions', released: 2003}), (thematrixreloaded:Movie {title: 'The Matrix Reloaded', released: 2003}), (thereplacements:Movie {title: 'The Replacements', released: 2000}), (thematrix:Movie {title: 'The Matrix', released: 1999}), (thedevilsadvocate:Movie {title: 'The Devils Advocate', released: 1997}), (keanu)-[:ACTED_IN]->(johnnymnemonic), (keanu)-[:ACTED_IN]->(somethingsgottagive), (keanu)-[:ACTED_IN]->(thematrixrevolutions), (keanu)-[:ACTED_IN]->(thematrixreloaded), (keanu)-[:ACTED_IN]->(thereplacements), (keanu)-[:ACTED_IN]->(thematrix), (keanu)-[:ACTED_IN]->(thedevilsadvocate) MATCH (a:Person {name: 'Keanu Reeves'}) RETURN [(a)-->(b) WHERE b:Movie | b.released] AS years

The whole predicate, including the WHERE keyword, is optional and may be omitted.