Filtering

Operators

When querying for data, a number of operators are available for different types in the where argument of a Query or Mutation.

Equality operators

All types can be tested for either equality or non-equality. For the Boolean type, these are the only available comparison operators.

Numerical operators

The following comparison operators are available for numeric types (Int, Float, BigInt), Temporal Types and Spatial Types:

  • _LT

  • _LTE

  • _GTE

  • _GT

Filtering of spatial types is different to filtering of numerical types and also offers an additional filter - see Spatial Types.

String comparison

The following case-sensitive comparison operators are only available for use on String and ID types:

  • _STARTS_WITH

  • _NOT_STARTS_WITH

  • _ENDS_WITH

  • _NOT_ENDS_WITH

  • _CONTAINS

  • _NOT_CONTAINS

RegEx matching

The filter _MATCHES is also available for comparison of String and ID types, which accepts a RegEx string as an argument and returns any matches. Note that RegEx matching filters are disabled by default.

To enable the inclusion of this filter, set the config option enableRegex to true.

The nature of RegEx matching means that on an unprotected API, this could potentially be used to execute a ReDoS attack (https://owasp.org/www-community/attacks/Regular_expression_Denial_of_Service_-_ReDoS) against the backing Neo4j database.

Array comparison

The following two comparison operators are available on non-array fields, and accept an array argument:

  • _IN

  • _NOT_IN

Conversely, the following operators are available on array fields, and accept a single argument:

  • _INCLUDES

  • _NOT_INCLUDES

These four operators are available for all types apart from Boolean.

Usage

Using the type definitions from Queries, below are some example of how filtering can be applied when querying for data.

At the root of a Query

By using the where argument on the Query field in question, you can return a User with a particular ID:

query {
    users(where: { id: "7CF1D9D6-E527-4ACD-9C2A-207AE0F5CB8C" }) {
        name
    }
}

Filtering relationships

By using the where argument on a relationship field, you can filter for a Post with a particular ID across all Users:

query {
    users {
        id
        name
        posts(where: { id: "2D297425-9BCF-4986-817F-F06EE0A1D9C7" }) {
            content
        }
    }
}

Aggregation Filtering

This library offers, for each relationship, an aggregation key inside the where argument. You can use the aggregation key to satisfy questions such as:

  • Find the posts where the number of likes are greater than 5

  • Find flights where the average age of passengers is greater than or equal to 18

  • Find movies where the shortest actor screen time is less than 10 minutes

You can use this where aggregation on both the node and edge of a relationship.

Aggregation Filtering Usage Examples

Find the posts where the number of likes are greater than 5

Given the schema:

type User {
    name: String
}

type Post {
    content: String
    likes: [User] @relationship(type: "LIKES", direction: IN)
}

Answering the question:

query {
    posts(where: { likesAggregate: { count_GT: 5 } }) {
        content
    }
}

Find flights where the average age of passengers is greater than or equal to 18

Given the schema:

type Passenger {
    name: String
    age: Int
}

type Flight {
    code: String
    passengers: [Passenger] @relationship(type: "FLYING_ON", direction: IN)
}

Answering the question:

query {
    flights(where: { passengersAggregate: { node: { age_AVERAGE_GTE: 18 } } }) {
        code
    }
}

Find movies where the shortest actor screen time is less than 10 minutes

Given the schema:

type Movie {
    title: String
    actors: [Person] @relationship(type: "ACTED_IN", direction: IN, properties: "ActedIn")
}

type Person {
    name: String
}

interface ActedIn {
    screenTime: Int
}

Answering the question:

query {
    movies(where: { actorsAggregate: { edge: { screenTime_MIN_LT: 10 } } }) {
        title
    }
}

Aggregation Filtering Operators

Below you will learn more about the autogenerated filters available on the aggregate key and for each type on the node and edge of the specified relationship.

Count

This is a special 'top level' key inside the where aggregation and will be available for all relationships. This is used to count the amount of relationships the parent node is connected to. The operators count has are as follows:

  • count_EQUAL

  • count_GT

  • count_GTE

  • count_LT

  • count_LTE

Example
query {
    posts(where: { likesAggregate: { count_GT: 5 } }) {
        content
    }
}

ID

You can only use the _EQUAL operator on types of ID.

String

Fields of type String have the following operators:

  • _EQUAL

  • _GT

  • _GTE

  • _LT

  • _LTE

  • _AVERAGE_EQUAL

  • _AVERAGE_GT

  • _AVERAGE_GTE

  • _AVERAGE_LT

  • _AVERAGE_LTE

  • _SHORTEST_EQUAL

  • _SHORTEST_GT

  • _SHORTEST_GTE

  • _SHORTEST_LT

  • _SHORTEST_LTE

  • _LONGEST_EQUAL

  • _LONGEST_GT

  • _LONGEST_GTE

  • _LONGEST_LT

  • _LONGEST_LTE

These operators are calculated against the length of each string.

Example
query {
    posts(where: { likesAggregate: { node: { name_LONGEST_GT: 5 } } }) {
        content
    }
}

Numerical Types

Numerical types include the following:

  • Int

  • Float

  • BigInt

The types in the list above have the following operators:

  • _EQUAL

  • _GT

  • _GTE

  • _LT

  • _LTE

  • _AVERAGE_EQUAL

  • _AVERAGE_GT

  • _AVERAGE_GTE

  • _AVERAGE_LT

  • _AVERAGE_LTE

  • _SUM_EQUAL

  • _SUM_GT

  • _SUM_GTE

  • _SUM_LT

  • _SUM_LTE

  • _MIN_EQUAL

  • _MIN_GT

  • _MIN_GTE

  • _MIN_LT

  • _MIN_LTE

  • _MAX_EQUAL

  • _MAX_GT

  • _MAX_GTE

  • _MAX_LT

  • _MAX_LTE

Example
query {
    movies(where: { actorsAggregate: { edge: { screenTime_MIN_LT: 10 } } }) {
        title
    }
}

Temporal Types

Temporal types include the following:

  • DateTime

  • LocalDateTime

  • LocalTime

  • Time

  • Duration

The types listed above have the following aggregation operators:

  • _EQUAL

  • _GT

  • _GTE

  • _LT

  • _LTE

  • _MIN_EQUAL

  • _MIN_GT

  • _MIN_GTE

  • _MIN_LT

  • _MIN_LTE

  • _MAX_EQUAL

  • _MAX_GT

  • _MAX_GTE

  • _MAX_LT

  • _MAX_LTE

Whilst the Duration type also has the following additional operators:

  • _AVERAGE_EQUAL

  • _AVERAGE_GT

  • _AVERAGE_GTE

  • _AVERAGE_LT

  • _AVERAGE_LTE