Predicate functions

Predicates are boolean functions that return true or false for a given set of non-null input. They are most commonly used to filter out paths in the WHERE part of a query.

Functions:

Diagram

1. all()

The function all() returns true if the predicate holds for all elements in the given list. null is returned if the list is null or all of its elements are null.

Syntax: all(variable IN list WHERE predicate)

Returns:

A Boolean.

Arguments:

Name Description

list

An expression that returns a list. A single element cannot be explicitly passed as a literal in the cypher statement. However, an implicit conversion will happen for single elements when passing node properties during cypher execution.

variable

A variable that can be used from within the predicate.

predicate

A predicate that is tested against all items in the list.

Query
MATCH p = (a)-[*1..3]->(b)
WHERE
  a.name = 'Alice'
  AND b.name = 'Daniel'
  AND all(x IN nodes(p) WHERE x.age > 30)
RETURN p

All nodes in the returned paths will have a property age with a value larger than 30.

Table 1. Result
p

(0)-[KNOWS,1]->(2)-[KNOWS,3]->(3)

Rows: 1

2. any()

The function any() returns true if the predicate holds for at least one element in the given list. null is returned if the list is null or all of its elements are null.

Syntax: any(variable IN list WHERE predicate)

Returns:

A Boolean.

Arguments:

Name Description

list

An expression that returns a list. A single element cannot be explicitly passed as a literal in the cypher statement. However, an implicit conversion will happen for single elements when passing node properties during cypher execution.

variable

A variable that can be used from within the predicate.

predicate

A predicate that is tested against all items in the list.

Query
MATCH (n)
WHERE any(color IN n.liked_colors WHERE color = 'yellow')
RETURN n

The query returns nodes with the property liked_colors (as a list), where at least one element has the value 'yellow'.

Table 2. Result
n

Node[4]{liked_colors:["pink","yellow","black"],name:"Eskil",eyes:"blue",age:41}

Rows: 1

3. exists()

The function exists() returns true if a match for the given pattern exists in the graph, or if the specified property exists in the node, relationship or map. null is returned if the input argument is null.

Syntax: exists(pattern-or-property)

Returns:

A Boolean.

Arguments:

Name Description

pattern-or-property

A pattern or a property (in the form 'variable.prop').

Query
MATCH (n)
WHERE exists(n.name)
RETURN
  n.name AS name,
  exists((n)-[:MARRIED]->()) AS is_married

The names of all nodes with the name property are returned, along with a boolean (true or false) indicating if they are married.

Table 3. Result
name is_married

"Alice"

false

"Bob"

true

"Charlie"

false

"Daniel"

false

"Eskil"

false

Rows: 5

Query
MATCH
  (a),
  (b)
WHERE
  exists(a.name)
  AND NOT exists(b.name)
OPTIONAL MATCH (c:DoesNotExist)
RETURN
  a.name AS a_name,
  b.name AS b_name,
  exists(b.name) AS b_has_name,
  c.name AS c_name,
  exists(c.name) AS c_has_name
ORDER BY a_name, b_name, c_name
LIMIT 1

Three nodes are returned: one with a property name, one without a property name, and one that does not exist (e.g., is null). This query exemplifies the behavior of exists() when operating on null nodes.

Table 4. Result
a_name b_name b_has_name c_name c_has_name

"Alice"

<null>

false

<null>

<null>

Rows: 1

4. none()

The function none() returns true if the predicate does not hold for any element in the given list. null is returned if the list is null or all of its elements are null.

Syntax: none(variable IN list WHERE predicate)

Returns:

A Boolean.

Arguments:

Name Description

list

An expression that returns a list. A single element cannot be explicitly passed as a literal in the cypher statement. However, an implicit conversion will happen for single elements when passing node properties during cypher execution.

variable

A variable that can be used from within the predicate.

predicate

A predicate that is tested against all items in the list.

Query
MATCH p = (n)-[*1..3]->(b)
WHERE
  n.name = 'Alice'
  AND none(x IN nodes(p) WHERE x.age = 25)
RETURN p

No node in the returned paths has a property age with the value 25.

Table 5. Result
p

(0)-[KNOWS,1]->(2)

(0)-[KNOWS,1]->(2)-[KNOWS,3]->(3)

Rows: 2

5. single()

The function single() returns true if the predicate holds for exactly one of the elements in the given list. null is returned if the list is null or all of its elements are null.

Syntax: single(variable IN list WHERE predicate)

Returns:

A Boolean.

Arguments:

Name Description

list

An expression that returns a list.

variable

A variable that can be used from within the predicate.

predicate

A predicate that is tested against all items in the list.

Query
MATCH p = (n)-->(b)
WHERE
  n.name = 'Alice'
  AND single(var IN nodes(p) WHERE var.eyes = 'blue')
RETURN p

In every returned path there is exactly one node that has a property eyes with the value 'blue'.

Table 6. Result
p

(0)-[KNOWS,0]->(1)

Rows: 1