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:

graph predicate functions

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.
Example 1. all()
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

[{"name":"Alice","eyes":"brown","age":38},{},{"name":"Charlie","eyes":"green","age":53},{"name":"Charlie","eyes":"green","age":53},{},{"name":"Daniel","eyes":"brown","age":54}]

Rows: 1

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.
Example 2. any()
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]{eyes:"blue",liked_colors:["pink","yellow","black"],name:"Eskil",age:41}

Rows: 1

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').
Example 3. exists()
Query
MATCH (n)
WHERE n.name IS NOT NULL
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
Example 4. exists()
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

Note that the exists() function is deprecated for property input. Please use the IS NOT NULL predicate instead.

isEmpty()

The function isEmpty() returns true if the given list or map contains no elements or if the given string contains no characters.

Syntax:

isEmpty(list)

Returns:

A Boolean.

Arguments:

Name Description

list

An expression that returns a list.
Example 5. isEmpty(list)
Query
MATCH (n)
WHERE NOT isEmpty(n.liked_colors)
RETURN n

The nodes with the property liked_colors being non-empty are returned.

Table 5. Result
n

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

Node[5]{eyes:"",liked_colors:["blue","green"],alias:"Frank",age:61}

Rows: 2

Syntax:

isEmpty(map)

Returns:

A Boolean.

Arguments:

Name Description

map

An expression that returns a map.
Example 6. isEmpty(map)
Query
MATCH (n)
WHERE isEmpty(properties(n))
RETURN n

Nodes that does not have any properties are returned.

Table 6. Result
n

Node[6]{}

Rows: 1

Syntax:

isEmpty(string)

Returns:

A Boolean.

Arguments:

Name Description

string

An expression that returns a string.
Example 7. isEmpty(string)
Query
MATCH (n)
WHERE isEmpty(n.eyes)
RETURN n.age AS age

The age are returned for each node that has a property eyes where the value evaulates to be empty (empty string).

Table 7. Result
age

61

Rows: 1

The function isEmpty(), like most other Cypher® functions, returns null if null is passed in to the function. That means that a predicate isEmpty(n.eyes) will filter out all nodes where the eyes property is not set. Thus, isEmpty() is not suited to test for null-values. IS NULL or IS NOT NULL should be used for that purpose.

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.
Example 8. none()
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 8. Result
p

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

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

Rows: 2

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.
Example 9. single()
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 9. Result
p

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

Rows: 1