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.

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 1. Result
list

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

Rows: 1

In the examples, you 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, you can use the square brackets again. This extracts from the start index and up to, but not including, the end index.

Query
RETURN range(0, 10)[3]
Table 2. Result
range(0, 10)[3]

3

Rows: 1

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

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

8

Rows: 1

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

Query
RETURN range(0, 10)[0..3]
Table 4. Result
range(0, 10)[0..3]

[0,1,2]

Rows: 1
Query
RETURN range(0, 10)[0..-5]
Table 5. Result
range(0, 10)[0..-5]

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

Rows: 1
Query
RETURN range(0, 10)[-5..]
Table 6. Result
range(0, 10)[-5..]

[6,7,8,9,10]

Rows: 1
Query
RETURN range(0, 10)[..4]
Table 7. Result
range(0, 10)[..4]

[0,1,2,3]

Rows: 1

Out-of-bound slices are simply truncated, but out-of-bound single elements return null.
Query
RETURN range(0, 10)[15]
Table 8. Result
range(0, 10)[15]

<null>

Rows: 1
Query
RETURN range(0, 10)[5..15]
Table 9. Result
range(0, 10)[5..15]

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

Rows: 1

You can get the size of a list as follows:

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

3

Rows: 1

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 11. Result
result

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

Rows: 1

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 12. Result
result

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

Rows: 1
Query
RETURN [x IN range(0,10) | x^3 ] AS result
Table 13. Result
result

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

Rows: 1

Pattern comprehension

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

The following graph is used for the pattern comprehension examples:

Graph
  N0 [
    label = "{Person|name = \'Keanu Reeves\'\l}"
  ]
  N0 -> N8 [
    color = "#2e3436"
    fontcolor = "#2e3436"
    label = "ACTED_IN\n"
  ]
  N0 -> N7 [
    color = "#2e3436"
    fontcolor = "#2e3436"
    label = "ACTED_IN\n"
  ]
  N0 -> N4 [
    color = "#2e3436"
    fontcolor = "#2e3436"
    label = "ACTED_IN\n"
  ]
  N0 -> N3 [
    color = "#2e3436"
    fontcolor = "#2e3436"
    label = "ACTED_IN\n"
  ]
  N0 -> N5 [
    color = "#2e3436"
    fontcolor = "#2e3436"
    label = "ACTED_IN\n"
  ]
  N0 -> N6 [
    color = "#2e3436"
    fontcolor = "#2e3436"
    label = "ACTED_IN\n"
  ]
  N0 -> N2 [
    color = "#2e3436"
    fontcolor = "#2e3436"
    label = "ACTED_IN\n"
  ]
  N0 -> N1 [
    color = "#2e3436"
    fontcolor = "#2e3436"
    label = "ACTED_IN\n"
  ]
  N1 [
    label = "{Movie|title = \'Johnny Mnemonic\'\lreleased = 1995\l}"
  ]
  N2 [
    label = "{Movie|title = \'Somethings Gotta Give\'\lreleased = 2003\l}"
  ]
  N3 [
    label = "{Movie|title = \'The Matrix Revolutions\'\lreleased = 2003\l}"
  ]
  N4 [
    label = "{Movie|title = \'The Matrix Reloaded\'\lreleased = 2003\l}"
  ]
  N5 [
    label = "{Movie|title = \'The Replacements\'\lreleased = 2000\l}"
  ]
  N6 [
    label = "{Movie|title = \'The Matrix\'\lreleased = 1999\l}"
  ]
  N7 [
    label = "{Movie|title = \'The Devils Advocate\'\lreleased = 1997\l}"
  ]
  N8 [
    label = "{Movie|title = \'The Matrix Resurrections\'\lreleased = 2021\l}"
  ]

This example returns a list that contains the year when the movies was released. The pattern matching in the pattern comprehension looks for Matrix in the movie title and that the node a (Person node with the name Keanu Reeves) has a relationship with the movie.

Query
MATCH (a:Person {name: 'Keanu Reeves'})
RETURN [(a)-->(b:Movie) WHERE b.title CONTAINS 'Matrix' | b.released] AS years
Table 14. Result
years

[2021,2003,2003,1999]

Rows: 1

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

This example returns a sorted list that contains years. The pattern matching in the pattern comprehension looks for movie nodes that has a relationship with the node a (Person node with the name Keanu Reeves).

Query
MATCH (a:Person {name: 'Keanu Reeves'})
WITH [(a)-->(b:Movie) | b.released] AS years
UNWIND years AS year
WITH year ORDER BY year
RETURN COLLECT(year) AS sorted_years
Table 15. Result
sorted_years

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

Rows: 1