Lists

Cypher^® includes comprehensive support for 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.