Filtering

1. Operators

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

1.1. Equality operators

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

1.2. Numerical operators

The following comparison operators are available for numeric types (Int, Float, BigInt), temporal types (DateTime) and spatial types (Point, CartesianPoint):

  • _LT

  • _LTE

  • _GTE

  • _GT

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

1.3. 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

1.3.1. 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.

We have added the ability to enable the inclusion of this filter by setting 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.

1.4. 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.

2. Usage

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

2.1. 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
    }
}

2.2. 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
        }
    }
}