Predicate functions - Cypher Manual

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()

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 if the predicate evaluates to null for at least one element and does not evaluate to false for any other element.

Syntax:

all(variable IN list WHERE predicate)

Returns:

BOOLEAN

Arguments:

Name Description

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.

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)-[*]->(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:

Table 1. 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

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 if the predicate evaluates to null for at least one element and does not evaluate to true for any other element.

Syntax:

any(variable IN list WHERE predicate)

Returns:

BOOLEAN

Arguments:

Name Description

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.

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 (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:

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

exists()

The function exists() returns true if a match for the given pattern exists in the graph.

null is returned if the input argument is null.

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

Syntax:

exists(pattern)

Returns:

BOOLEAN

Arguments:

Name Description

Name	Description
`pattern`	A pattern.

pattern

A pattern.

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.

Table 3. 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

The function exists() looks very similar to the expression EXISTS { ... }, but they are not related.

See Using EXISTS subqueries for more information.

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:

BOOLEAN

Arguments:

Name Description

Name	Description
`list`	An expression that returns a list.

list

An expression that returns a list.

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):

Table 4. Result
p.name	p.nationality
`"Keanu Reeves"`	`"Canadian"`
`"Carrie Anne Moss"`	`"American"`
`"Liam Neeson"`	`"Northern Irish"`
`"Guy Pearce"`	`"Australian"`
`"Kathryn Bigelow"`	`"American"`
Rows: 5

Syntax:

isEmpty(map)

Returns:

BOOLEAN

Arguments:

Name Description

Name	Description
`map`	An expression that returns a map.

map

An expression that returns a map.

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)

Syntax:

isEmpty(string)

Returns:

BOOLEAN

Arguments:

Name Description

Name	Description
`string`	An expression that returns a string.

string

An expression that returns a string.

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 (empty string) address property is returned:

Table 5. 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()

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 if the predicate evaluates to null for at least one element and does not evaluate to true for any other element.

Syntax:

none(variable IN list WHERE predicate)

Returns:

BOOLEAN

Arguments:

Name Description

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.

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 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:

Table 6. 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

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 if the predicate evaluates to null for at least one element and true for max one element.

Syntax:

single(variable IN list WHERE predicate)

Returns:

BOOLEAN

Arguments:

Name Description

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.

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 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 the nationality property value Northern Irish:

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