Predicate functions

Introduction

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.

Example graph

The following graph is used for the examples below:

To recreate it, run the following query against an empty Neo4j database:

CREATE
  (keanu:Person {name:'Keanu Reeves', age:58, nationality:'Canadian'}),
  (carrie:Person {name:'Carrie Anne Moss', age:55, nationality:'American'}),
  (liam:Person {name:'Liam Neeson', age:70, nationality:'Northern Irish'}),
  (guy:Person {name:'Guy Pearce', age:55, nationality:'Australian'}),
  (kathryn:Person {name:'Kathryn Bigelow', age:71, nationality:'American'}),
  (jessica:Person {name:'Jessica Chastain', age:45, address:''}),
  (theMatrix:Movie {title:'The Matrix'}),
  (keanu)-[:KNOWS {since: 1999}]->(carrie),
  (keanu)-[:KNOWS {since: 2005}]->(liam),
  (keanu)-[:KNOWS {since: 2010}]->(kathryn),
  (kathryn)-[:KNOWS {since: 2012}]->(jessica),
  (carrie)-[:KNOWS {since: 2008}]->(guy),
  (liam)-[:KNOWS {since: 2009}]->(guy),
  (keanu)-[:ACTED_IN]->(theMatrix),
  (carrie)-[:ACTED_IN]->(theMatrix)

all()

Details

Syntax

all(variable IN list WHERE predicate)

Description

Returns true if the predicate holds for all elements in the given LIST<ANY>.

Arguments

Name

Type

Description

variable

ANY

A variable that can be used within the WHERE clause.

list

LIST<ANY>

A predicate must hold for all elements in this list for the function to return true.

predicate

ANY

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

Returns

BOOLEAN

Considerations

all() differs from most Cypher® functions because it iterates over a list, evaluating an expression for each element, rather than returning a result from a single evaluation.

null is returned if the list is null or if the predicate evaluates to null for at least one element and does not evaluate to false for any other element.

all() returns true if list is empty because there are no elements to falsify the predicate.

Example 1. all()
Find paths where all nodes meet a given property value
MATCH p = (a:Person {name: 'Keanu Reeves'})-[]-{2,}()
WHERE all(x IN nodes(p) WHERE x.age < 60)
RETURN [n IN nodes(p) | n.name] AS actorsList

All nodes in the returned paths have an age`property below `60:

Result
actorsList

["Keanu Reeves", "Carrie Anne Moss", "Guy Pearce"]

Rows: 2

all() on an empty LIST
WITH [] as emptyList
RETURN all(i in emptyList WHERE true) as allTrue, all(i in emptyList WHERE false) as allFalse
Result
allTrue allFalse

TRUE

TRUE

Rows: 1

allReduce()

Details

Syntax

allReduce(accumulator = initial, stepVariable IN list | reductionFunction, predicate)

Description

Returns true if, during the stepwise evaluation of a value across the elements in a given LIST<ANY>, the accumulated result satisfies a specified predicate at every step. Where that list is a group variable defined in a quantified path pattern, it allows for the early pruning of paths that do not satisfy the predicate.

Arguments

Name

Type

Description

accumulator

ANY

A variable that holds the result of the reductionFunction as the list is iterated. It is initialized with the value of initial.

initial

ANY

The value of the accumulator for the first evaluation of reductionFunction.

stepVariable

ANY

A variable that holds the value of each element of list during iteration.

list

LIST<ANY>

The list that is being iterated over.

reductionFunction

ANY

An expression whose return value becomes the next value of the accumulator. The return type must match the return type of initial.

predicate

BOOLEAN

A predicate that is evaluated for each iteration. It has access to the variable accumulator, but not stepVariable.

Returns

BOOLEAN

Considerations

allReduce() differs from most Cypher functions because it iterates over a list, evaluating an expression for each element, rather than returning a result from a single evaluation.

allReduce() combines the functionality of the all() and reduce() functions.

If all evaluations of predicate are true, allReduce() will return true.

If any evaluations of predicate are false, allReduce() will return false.

allReduce() returns true if list is empty because there are no elements to falsify the predicate.

null is returned if the list is null or if the predicate evaluates to null for at least one element and does not evaluate to false for any other element.

Example 2. allReduce()

The below query finds KNOWS paths with a length of 3 where the accumulator begins with first node’s age and the accumulated age values of all nodes in the path never exceeds 230. Paths that do not meet this requirement are excluded, such as the path with the sequence ["Keanu Reeves (58)", "Carrie Anne Moss (55)", "Guy Pearce (55)", "Liam Neeson (70)"] which has an aggregated age value of 238.

Find aggregated ages within a boundary
MATCH (s) (()-[:KNOWS]-(n)){3}
WHERE allReduce(
  acc = s.age,
  node IN n | acc + node.age,
  acc < 230
)
RETURN [i IN [s] + n | i.name || " (" + toString(i.age) || ")"] AS ageSequence,
      reduce(acc = 0, node IN [s] + n | acc + node.age) AS aggregatedAges
ORDER BY aggregatedAges
Result
ageSequence aggregatedAges

["Carrie Anne Moss (55)", "Keanu Reeves (58)", "Kathryn Bigelow (71)", "Jessica Chastain (45)"]

229

["Jessica Chastain (45)", "Kathryn Bigelow (71)", "Keanu Reeves (58)", "Carrie Anne Moss (55)"]

229

Rows: 2

The next query uses allReduce() to compare neighboring relationships. It finds KNOWS paths with a length of at least 3 where each relationship’s since value is greater than the previous one and above 2000.

Find paths where a relationship property must be above a value and increase along a path
MATCH path = ()-[r:KNOWS]-{3,}()
WHERE allReduce(
  span = {},
  rel IN r | { previous: span.current, current: rel.since },
  (span.previous IS NULL OR span.previous < span.current) AND span.current > 2000
)
LET people = nodes(path)
RETURN [actor IN people | actor.name] AS connectedActors,
       [rel IN r | rel.since] AS sinceYears
ORDER BY sinceYears
Result
connectedActors sinceYears

["Liam Neeson", "Keanu Reeves", "Kathryn Bigelow", "Jessica Chastain"]

[2005, 2010, 2012]

Rows: 1

any()

Details

Syntax

any(variable IN list WHERE predicate)

Description

Returns true if the predicate holds for at least one element in the given LIST<ANY>.

Arguments

Name

Type

Description

variable

ANY

A variable that can be used within the WHERE clause.

list

LIST<ANY>

A predicate must hold for all elements in this list for the function to return true.

predicate

ANY

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

Returns

BOOLEAN

Considerations

any() differs from most Cypher functions because it iterates over a list, evaluating an expression for each element, rather than returning a result from a single evaluation.

null is returned if the list is null or if the predicate evaluates to null for at least one element and does not evaluate to false for any other element.

any() returns false if list is empty because there are no elements to satisfy the predicate.

Example 3. any()
Find paths where at least one relationship property is above a given threshold
MATCH p = (n:Person {name: 'Keanu Reeves'})-[:KNOWS]-{3}()
WHERE any(rel IN relationships(p) WHERE rel.since < 2000)
RETURN [person IN nodes(p) | person.name] AS connectedActors,
       [rel IN relationships(p) | rel.since] AS sinceYears
Result
connectedActors sinceYears

["Keanu Reeves", "Carrie Anne Moss", "Guy Pearce", "Liam Neeson"]

[1999, 2008, 2009]

Rows: 1

any() on an empty LIST
WITH [] as emptyList
RETURN any(i IN emptyList WHERE true) as anyTrue, any(i IN emptyList WHERE false) as anyFalse
Result
anyTrue anyFalse

false

false

Rows: 1

exists()

Details

Syntax

exists(input)

Description

Returns true if a match for the pattern exists in the graph.

Arguments

Name

Type

Description

input

ANY

A pattern to verify the existence of.

Returns

BOOLEAN

Considerations

null is returned if input is null.

To check if a property is not null use the IS NOT NULL predicate.

Example 4. exists()
Query
MATCH (p:Person)
RETURN p.name AS name,
       exists((p)-[:ACTED_IN]->()) AS has_acted_in_rel

This query returns the name property of every Person node, along with a boolean (true or false) indicating if those nodes have an ACTED_IN relationship in the graph.

Result
name has_acted_in_rel

"Carrie Anne Moss"

true

"Keanu Reeves"

true

"Liam Neeson"

false

"Guy Pearce"

false

"Kathryn Bigelow"

false

"Jessica Chastain"

false

Rows: 6

For information about the EXISTS subquery, which is more versatile than the exists() function, see EXISTS subqueries.

isEmpty()

Details

Syntax

isEmpty(input)

Description

Checks whether a STRING, MAP or LIST<ANY> is empty.

Arguments

Name

Type

Description

input

STRING | MAP | LIST<ANY>

A value to be checked for emptiness.

Returns

BOOLEAN

Example 5. isEmpty(list)
Query
MATCH (p:Person)
WHERE NOT isEmpty(p.nationality)
RETURN p.name, p.nationality

This query returns every Person node in the graph with a set nationality property value (i.e., all Person nodes except for Jessica Chastain):

Result
p.name p.nationality

"Keanu Reeves"

"Canadian"

"Carrie Anne Moss"

"American"

"Liam Neeson"

"Northern Irish"

"Guy Pearce"

"Australian"

"Kathryn Bigelow"

"American"

Rows: 5

Example 6. isEmpty(map)
Query
MATCH (n)
WHERE isEmpty(properties(n))
RETURN n

Because the example graph contains no empty nodes, nothing is returned:

Result
(no changes, no records)
Example 7. isEmpty(string)
Query
MATCH (p:Person)
WHERE isEmpty(p.address)
RETURN p.name AS name

The name property of each node that has an empty STRING address property is returned:

Result
name

"Jessica Chastain"

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.address) will filter out all nodes where the address 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()

Details

Syntax

none(variable IN list WHERE predicate)

Description

Returns true if the predicate holds for no element in the given LIST<ANY>.

Arguments

Name

Type

Description

variable

ANY

A variable that can be used within the WHERE clause.

list

LIST<ANY>

A predicate must hold for all elements in this list for the function to return true.

predicate

ANY

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

Returns

BOOLEAN

Considerations

none() differs from most Cypher functions because it iterates over a list, evaluating an expression for each element, rather than returning a result from a single evaluation.

null is returned if the list is null, or if the predicate evaluates to null for at least one element and does not evaluate to true for any other element.

none() returns true if list is empty because there are no elements to violate the predicate.

Example 8. none()
Find paths where no node exceeds a given property value
MATCH p = (n:Person {name: 'Keanu Reeves'})-[]-{2}()
WHERE none(x IN nodes(p) WHERE x.age > 60)
RETURN [x IN nodes(p) | x.name] AS connectedActors

No nodes in the returned paths have an age property with a greater value than 60:

Result
connectedActors

["Keanu Reeves", "Carrie Anne Moss", "Guy Pearce"]

Rows: 1

none() on an empty LIST
WITH [] as emptyList
RETURN none(i IN emptyList WHERE true) as noneTrue, none(i IN emptyList WHERE false) as noneFalse
Result
noneTrue noneFalse

TRUE

TRUE

Rows: 1

single()

Details

Syntax

single(variable IN list WHERE predicate)

Description

Returns true if the predicate holds for exactly one of the elements in the given LIST<ANY>.

Arguments

Name

Type

Description

variable

ANY

A variable that can be used within the WHERE clause.

list

LIST<ANY>

A predicate must hold for all elements in this list for the function to return true.

predicate

ANY

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

Returns

BOOLEAN

Considerations

single() differs from most Cypher functions because it iterates over a list, evaluating an expression for each element, rather than returning a result from a single evaluation.

null is returned if the list is null, or if the predicate evaluates to null for at least one element and does not evaluate to true for any other element.

single() returns false if list is empty because there is not exactly one element satisfying the predicate.

Example 9. single()
Find paths where exactly one node has a given property value
MATCH p = (n:Person {name: 'Keanu Reeves'})-[:KNOWS]-+(b)
WHERE single(x IN [b] WHERE x.nationality = 'Northern Irish')
RETURN [person IN nodes(p) | person.name + " (" + person.nationality + ")"] AS northernIrishPaths
ORDER BY length(p)
Result
northernIrishPaths

["Keanu Reeves (Canadian)", "Liam Neeson (Northern Irish)"]

["Keanu Reeves (Canadian)", "Carrie Anne Moss (American)", "Guy Pearce (Australian)", "Liam Neeson (Northern Irish)"]

Rows: 2

single() on an empty LIST
WITH [] as emptyList
RETURN single(i IN emptyList WHERE true) as singleTrue, single(i IN emptyList WHERE false) as singleFalse
Result
singleTrue singleFalse

false

false

Rows: 1