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
}
}
GraphiQL
Query Variables

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
}
}
GraphiQL
Query Variables

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
}
}
GraphiQL
Query Variables

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
}
}
}
GraphiQL
Query Variables

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
}
}
}
GraphiQL
Query Variables

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
}
}
}
}
GraphiQL
Query Variables

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

GraphQL query

{
Business(
filter: {
location_distance_lt: {
point: { latitude: 46.859924, longitude: -113.985402 }
distance: 1500
}
}
) {
name
location {
latitude
longitude
}
}
}

GraphQL result

{
"data": {
"Business": [
{
"name": "Missoula Public Library",
"location": {
"latitude": 46.870035,
"longitude": -113.990976
}
},
{
"name": "Market on Front",
"location": {
"latitude": 46.869824,
"longitude": -113.993633
}
}
]
}
}

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.

FieldTypeExplanation
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
movieIdIDMatches nodes when value is an exact match
movieId_notIDMatches 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
String fields
titleStringMatches nodes based on equality of value
title_notStringMatches 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_containsStringMatches nodes when value contains given substring
title_not_containsStringMatches nodes when value does not contain given substring
title_starts_withStringMatches nodes when value starts with given substring
title_not_starts_withStringMatches nodes when value does not start with given substring
title_ends_withStringMatches nodes when value ends with given substring
title_not_ends_withStringMatches nodes when value does not end with given substring
Numeric fieldsSimilar behavior for float fields
yearIntMatches nodes when value is an exact match
year_notIntMatches 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_ltIntMatches nodes when value is less than given integer
year_lteIntMatches nodes when value is less than or equal to given integer
year_gtIntMatches nodes when value is greater than given integer
year_gteIntMatches nodes when value is greater than or equal to given integer
Enum fields
ratingRATING_ENUMMatches nodes based on enum value
rating_notRATING_ENUMMatches 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
availableBooleanMatches nodes based on value
available_notBooleanMatches nodes base on inequality of value
Relationship fieldsUse a relationship field filter to apply a nested filter to matches at the root level
actors_ActorFilterMatches nodes based on a filter of the related node
actors_not_ActorFilterMatches 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_ActorFilterMatches nodes when at least one of the related nodes is a match
actors_none_ActorFilterMatches nodes when none of the related nodes are a match
actors_single_ActorFilterMatches nodes when exactly one of the related nodes is a match
actors_every_ActorFilterMatches nodes when all related nodes are a match
Temporal fieldsTemporal filters use the temporal inputs described in the Temporal Types (DateTime) section
createdAt_Neo4jDateTimeInputMatches when date is an exact match
createdAt_not_Neo4jDateTimeInputMatches 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_Neo4jDateTimeInputMatches when value is less than given DateTime
createdAt_lte_Neo4jDateTimeInputMatches when value is less than or equal to given DateTime
createdAt_gt_Neo4jDateTimeInputMatches when value is greater than given DateTime
cratedAt_gte_Neo4jDateTimeInputMatches when value is greater than or equal to given DateTime
Spatial fieldsSpatial filers use the point inputs described in the Spatial Types section
location_Neo4jPointInputMatches point property exactly
location_not_Neo4jPointInputMatches based on inequality of point values
location_distance_Neo4jPointDistanceFilterMatches based on computed distance of location to provided point
location_distance_lt_Neo4jPointDistanceFilterMatches when computed distance of location to provided point is less than distance specified
location_distance_lte_Neo4jPointDistanceFilterMatches when computed distance of location to provided point is less than or equal to distance specified
location_distance_gt_Neo4jPointDistanceFilterMatches when computed distance of location to provided point is greater than distance specified
location_distance_gte_Neo4jPointDistanceFilterMatches 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