Skip to content
This repository has been archived by the owner. It is now read-only.
Permalink
master
Switch branches/tags
Go to file
 
 
Cannot retrieve contributors at this time

Complex GraphQL Filtering

A filter argument is added to field arguments, as well as input types used to support them.

Filtering is currently supported for scalar fields, enums, @relation fields and types. Filtering on @cypher directive fields is not yet supported.

filter Argument

The auto-generated filter argument is used to support complex filtering in queries. For example, to filter for Movies released before 1920:

{
  Movie(filter: { year_lt: 1920 }) {
    title
    year
  }
}

Nested Filter

To filter based on the results of nested fields applied to the root, simply nest the filters used. For example, to search for movies whose title starts with "River" and has at least one actor whose name starts with "Brad":

{
  Movie(
    filter: {
      title_starts_with: "River"
      actors_some: { name_contains: "Brad" }
    }
  ) {
    title
  }
}

Logical Operators: AND, OR

Filters can be wrapped in logical operations AND and OR. For example, to find movies that were released before 1920 or have a title that contains "River Runs":

{
  Movie(filter: { OR: [{ year_lt: 1920 }, { title_contains: "River Runs" }] }) {
    title
    year
  }
}

These logical operators can be nested as well. For example, find movies that there were released before 1920 or have a title that contains "River" and belong to the genre "Drama":

{
  Movie(
    filter: {
      OR: [
        { year_lt: 1920 }
        {
          AND: [{ title_contains: "River" }, { genres_some: { name: "Drama" } }]
        }
      ]
    }
  ) {
    title
    year
    genres {
      name
    }
  }
}

Regular Expressions: regexp

The Cypher regular expression filter is generated for ID and String type fields. The value provided should follow the Java syntax for regular expressions.

For example, to find movies where the title property has the value river (case-insensitive):

{
  Movie(filter: { title_regexp: "(?i)river.*" }) {
    title
    year
  }
}

Filtering In Selections

Filters can be used in not only the root query argument, but also throughout the selection set. For example, search for all movies that contain the string "River", and when returning the genres of the these movies only return genres with the name "Drama":

{
  Movie(filter: { title_contains: "River" }) {
    title
    genres(filter: { name: "Drama" }) {
      name
    }
  }
}

DateTime Filtering

Filtering can be applied to GraphQL temporal fields, using the temporal input types described in the Temporal Types (DateTime) section. For example, filter for reviews created before January 1, 2015:

{
  User(first: 1) {
    rated(filter: { created_lt: { year: 2015, month: 1, day: 1 } }) {
      rating
      created {
        formatted
      }
    }
  }
}

Spatial Filtering

When querying using point data, often we want to find things that are close to other things. For example, what businesses are within 1.5km of me?

For points using the Geographic coordinate reference system (latitude and longitude) distance is measured in meters.

Filter Criteria

The filter criteria available depends on the type of the field and are added to the generated input type prefixed by the name of the field and suffixed with the criteria. For example, given the following type definitions:

enum RATING {
  G
  PG
  PG13
  R
}

type Movie {
  movieId: ID!
  title: String
  year: Int
  rating: RATING
  available: Boolean
  actors: [Actor] @relation(name: "ACTED_IN", direction: IN)
  reviews: [UserReview]
}

type Actor {
  name: String
}

type User {
  name: String
  rated: UserReview
}

type UserReview @relation(name: "RATED") {
  from: User
  to: Movie
  rating: Float
  createdAt: DateTime
}

type Business {
  id: ID!
  name: String
  location: Point
}

the following filtering criteria is available, through the generated filter input type.

This table shows the fields available on the generated filter input type, and a brief explanation of each filter criteria.

Field Type Explanation
Logical operators
AND [_MovieFilter] Use to apply logical AND to a list of filters, typically used when nested with OR operators
OR [_MovieFilter] Use to apply logical OR to a list of filters.
ID fields
movieId ID Matches nodes when value is an exact match
movieId_not ID Matches nodes when value is not an exact match
movieId_in [ID!] Matches nodes based on equality of at least one value in list of values
movieId_not_in [ID!] Matches nodes based on inequality of all values in list of values
movieId_regexp String Matches nodes given provided regular expression
String fields
title String Matches nodes based on equality of value
title_not String Matches nodes based on inequality of value
title_in [String!] Matches nodes based on equality of at least one value in list
title_not_in [String!] Matches nodes based on inequality of all values in list
title_regexp String Matches nodes given provided regular expression
title_contains String Matches nodes when value contains given substring
title_not_contains String Matches nodes when value does not contain given substring
title_starts_with String Matches nodes when value starts with given substring
title_not_starts_with String Matches nodes when value does not start with given substring
title_ends_with String Matches nodes when value ends with given substring
title_not_ends_with String Matches nodes when value does not end with given substring
Numeric fields Similar behavior for float fields
year Int Matches nodes when value is an exact match
year_not Int Matches nodes based on inequality of value
year_in [Int!] Matches nodes based on equality of at least one value in list
year_not_in [Int!] Matches nodes based on inequality of all values in list
year_lt Int Matches nodes when value is less than given integer
year_lte Int Matches nodes when value is less than or equal to given integer
year_gt Int Matches nodes when value is greater than given integer
year_gte Int Matches nodes when value is greater than or equal to given integer
Enum fields
rating RATING_ENUM Matches nodes based on enum value
rating_not RATING_ENUM Matches nodes based on inequality of enum value
rating_in [RATING_ENUM!] Matches nodes based on equality of at least one enum value in list
rating_not_in [RATING_ENUM!] Matches nodes based on inequality of all values in list
Boolean fields
available Boolean Matches nodes based on value
available_not Boolean Matches nodes base on inequality of value
Relationship fields Use a relationship field filter to apply a nested filter to matches at the root level
actors _ActorFilter Matches nodes based on a filter of the related node
actors_not _ActorFilter Matches nodes when a filter of the related node is not a match
actors_in [_ActorFilter!] Matches nodes when the filter matches at least one of the related nodes
actors_not_in [_ActorFilter!] Matches nodes when the filter matches none of the related nodes
actors_some _ActorFilter Matches nodes when at least one of the related nodes is a match
actors_none _ActorFilter Matches nodes when none of the related nodes are a match
actors_single _ActorFilter Matches nodes when exactly one of the related nodes is a match
actors_every _ActorFilter Matches nodes when all related nodes are a match
Temporal fields Temporal filters use the temporal inputs described in the Temporal Types (DateTime) section
createdAt _Neo4jDateTimeInput Matches when date is an exact match
createdAt_not _Neo4jDateTimeInput Matches based on inequality of value
createdAt_in [_Neo4jDateTimeInput] Matches based on equality of at least one value in list
createdAt_not_in [_Neo4jDateTimeInput] Matches based on inequality of all values in list
createdAt_lt _Neo4jDateTimeInput Matches when value is less than given DateTime
createdAt_lte _Neo4jDateTimeInput Matches when value is less than or equal to given DateTime
createdAt_gt _Neo4jDateTimeInput Matches when value is greater than given DateTime
cratedAt_gte _Neo4jDateTimeInput Matches when value is greater than or equal to given DateTime
Spatial fields Spatial filers use the point inputs described in the Spatial Types section
location _Neo4jPointInput Matches point property exactly
location_not _Neo4jPointInput Matches based on inequality of point values
location_distance _Neo4jPointDistanceFilter Matches based on computed distance of location to provided point
location_distance_lt _Neo4jPointDistanceFilter Matches when computed distance of location to provided point is less than distance specified
location_distance_lte _Neo4jPointDistanceFilter Matches when computed distance of location to provided point is less than or equal to distance specified
location_distance_gt _Neo4jPointDistanceFilter Matches when computed distance of location to provided point is greater than distance specified
location_distance_gte _Neo4jPointDistanceFilter Matches when computed distance of location to provided point is greater than or equal to distance specified

See the filtering tests for more examples of the use of filters.

Resources