Queries

Using neo4j-graphql-js, all of the arguments for a Query were root-level arguments. For example, for the following simple type definition:

type Movie {
    title: String!
    averageRating: Float
}

The following Query would have been generated:

type Query {
    Movie(title: String, averageRating: Float, first: Int, offset: Int, orderBy: [_MovieOrdering], filter: _MovieFilter): [Movie]
}

In @neo4j/graphql, the ethos has been to simplify the top-level arguments:

type Query {
    movies(where: MovieWhere, options: MovieOptions): [Movie]!
}

Changes to note for migration:

  • Query fields were previously named in the singular, and in PascalCase - they are now pluralized and in camelCase

  • Query return types were previously in nullable lists of nullable types - they are now non-nullable lists of non-nullable types, e.g. [Movie] is now [Movie!]!; ensuring either an array of defined Movie objects or an empty array.

  • In this example, the _MovieFilter type has essentially been renamed to MovieWhere, the filter arguments renamed to where, and the top-level field arguments title and averageRating removed - see Filtering (where) below

  • The first, offset and orderBy have been collapsed into the MovieOptions type and renamed limit, offset and sort, respectively - see Sorting and Pagination (options) below

Filtering (where)

Simple equality fields are no longer available at the root of Query fields. As a simple demonstration, a simple query using neo4j-graphql-js that looked like:

query {
    Movie(title: "Forrest Gump") {
        averageRating
    }
}

Is now changed to the following using @neo4j/graphql:

query {
    movies(where: { title: "Forrest Gump" }) {
        averageRating
    }
}

When discussing how the field where of type MovieWhere differs to the field filter of _MovieFilter the following table can be used for guidance:

Table 1. Comparing the fields of the _MovieFilter and MovieWhere types
neo4j-graphql-js @neo4j/graphql

AND: [_MovieFilter!]

AND: [MovieWhere!]

OR: [_MovieFilter!]

OR: [MovieWhere!]

title: String

title: String

title_not: String

title_NOT: String

title_in: [String!]

title_IN: [String]

title_not_in: [String!]

title_NOT_IN: [String]

title_contains: String

title_CONTAINS: String

title_not_contains: String

title_NOT_CONTAINS: String

title_starts_with: String

title_STARTS_WITH: String

title_not_starts_with: String

title_NOT_STARTS_WITH: String

title_ends_with: String

title_ENDS_WITH: String

title_not_ends_with: String

title_NOT_ENDS_WITH: String

title_regexp: String

title_MATCHES: String

averageRating: Float

averageRating: Float

averageRating_not: Float

averageRating_NOT: Float

averageRating_in: [Float!]

averageRating_IN: [Float]

averageRating_not_in: [Float!]

averageRating_NOT_IN: [Float]

averageRating_lt: Float

averageRating_LT: Float

averageRating_lte: Float

averageRating_LTE: Float

averageRating_gt: Float

averageRating_GT: Float

averageRating_gte: Float

averageRating_GTE: Float

For filtering on relationship fields, the _some, _none, _single and _every filters are not yet implemented.

Sorting and Pagination (options)

Sorting

Sorting has changed somewhat in @neo4j/graphql. For the example being used in this page, the _MovieOrdering type in neo4j-graphql-js was an enum which looked like the following:

enum _MovieOrdering {
    title_asc
    title_desc
    averageRating_asc
    averageRating_desc
}

You could then query all movies ordered by title ascending by executing:

query {
    Movie(orderBy: [title_asc]) {
        title
    }
}

In @neo4j/graphql, the sorting type MovieSort has become an input type with each field as an enum, like follows:

enum SortDirection {
    ASC
    DESC
}

input MovieSort {
    title: SortDirection
    averageRating: SortDirection
}

To fetch all movies sorted by title ascending as per above, you would execute:

query {
    movies(options: { sort: [{ title: ASC }] }) {
        title
    }
}

Pagination

Pagination is broadly similar, with the arguments just renamed and moved a level deeper. For example, to return "page 3, with 10 results per page" using neo4j-graphql-js was:

query {
    Movie(offset: 20, first: 10) {
        title
    }
}

Using @neo4j/graphql, this will now be:

query {
    movies(options: { offset: 20, limit: 10 }) {
        title
    }
}