Lists

Cypher^® includes comprehensive support for lists. This section first describes lists in general, and then discusses how to use list comprehension and pattern comprehension in lists.

For information about the list predicate operator IN, which checks for list membership, see Expressions → Predicates → List operators. For information list concatenation (+ and ||), list element access and slicing ([]), as well as list and pattern comprehensions, see List expressions.

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

A list can consist of different value types.

Query

RETURN [0, "hello", 3.14, null] AS list

Table 2. Result
list
`[0, "hello", 3.14, null]`
Rows: 1

Lists are indexed by 0 in Cypher. To access individual elements in a list, use square brackets. This extracts from the start index and up to, but not including, the end index.

For example:

Query

WITH [5,1,7] AS list
RETURN list[2]

Table 3. Result
list[2]
`7`
Rows: 1

List range and size

The below examples use the range function to create lists. This function returns a list containing all numbers between given start and end numbers. The range is inclusive in both ends.

Query

RETURN range(0, 10)[3] AS element

Table 4. Result
element
`3`
Rows: 1

It is also possible to use negative numbers, to start from the end of the list instead.

Query

RETURN range(0, 10)[-3] AS element

Table 5. Result
element
`8`
Rows: 1

Finally, it is possible to use ranges inside the brackets to return ranges of the list. The list range operator ([]) is inclusive of the first value, but exclusive of the last value.

Query

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

Table 6. Result
list
`[0,1,2]`
Rows: 1

Query

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

Table 7. Result
list
`[0,1,2,3,4,5]`
Rows: 1

Query

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

Table 8. Result
list
`[6,7,8,9,10]`
Rows: 1

Query

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

Table 9. Result
list
`[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] AS list

Table 10. Result
list
`<null>`
Rows: 1

Query

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

Table 11. Result
list
`[5,6,7,8,9,10]`
Rows: 1

The size of a list can be obtained as follows:

Query

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

Table 12. Result
list
`3`
Rows: 1

Storing lists as properties

It is possible to store homogenous lists of simple values as properties.

Allowed - store homogenous list as a property

CREATE (n:Label)
SET n.listProperty = [1, 2, 3]
RETURN n.listProperty AS homogenousListProperty

Table 13. Result
homogenousListProperty
`[1, 2, 3]`
Rows: 1

It is not, however, possible to store heterogeneous lists as properties.

Not allowed - store heterogenous list as a property

CREATE (n:Label)
SET n.listProperty = [1, "hello", .45, date()]
RETURN n.listProperty AS heterogenousListProperty

Error

Neo4j only supports a subset of Cypher types for storage as singleton or array properties. Please refer to section cypher/syntax/values of the manual for more details.