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]->(carrie),
  (keanu)-[:KNOWS]->(liam),
  (keanu)-[:KNOWS]->(kathryn),
  (kathryn)-[:KNOWS]->(jessica),
  (carrie)-[:KNOWS]->(guy),
  (liam)-[:KNOWS]->(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()

Query

MATCH p = (a)-[*]->(b)
WHERE
  a.name = 'Keanu Reeves'
  AND b.name = 'Guy Pearce'
  AND all(x IN nodes(p) WHERE x.age < 60)
RETURN p

All nodes in the returned paths will have a property age with a value lower than 60:

Result
p
`(:Person {nationality: "Canadian",name: "Keanu Reeves",age: 58})-[:KNOWS]->(:Person {nationality: "American",name: "Carrie Anne Moss",age: 55})-[:KNOWS]->(:Person {nationality: "Australian",name: "Guy Pearce",age: 55})`
Rows: 1

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

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 2. any()

Query

MATCH (p:Person)
WHERE any(nationality IN p.nationality WHERE nationality = 'American')
RETURN p

The query returns the Person nodes with the nationality property value American:

Result
p
`{"nationality":"American","name":"Carrie Anne Moss","age":55}`
`{"nationality":"American","name":"Kathryn Bigelow","age":71}`
Rows: 2

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 3. 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 4. 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 5. 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 6. 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 7. none()

Query

MATCH p = (n)-[*]->(b)
WHERE
  n.name = 'Keanu Reeves'
  AND none(x IN nodes(p) WHERE x.age > 60)
RETURN p

No node in the returned path has an age property with a greater value than 60:

Result
p
`(:Person {nationality: "Canadian",name: "Keanu Reeves",age: 58})-[:KNOWS]→(:Person {nationality: "American",name: "Carrie Anne Moss",age: 55})`
`(:Person {nationality: "Canadian",name: "Keanu Reeves",age: 58})-[:KNOWS]→(:Person {nationality: "American",name: "Carrie Anne Moss",age: 55})-[:KNOWS]→(:Person {nationality: "Australian",name: "Guy Pearce",age: 55})`
Rows: 2

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 8. single()

Query

MATCH p = (n)-->(b)
WHERE
  n.name = 'Keanu Reeves'
  AND single(x IN nodes(p) WHERE x.nationality = 'Northern Irish')
RETURN p

In every returned path there is exactly one node which has the nationality property value Northern Irish:

Result
p
`(:Person {nationality: "Canadian",name: "Keanu Reeves",age: 58})-[:KNOWS]→(:Person {nationality: "Northern Irish",name: "Liam Neeson",age: 70})`
Rows: 1

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