Types

Neo4j GraphQL supports all of the default GraphQL scalar types as well as additional scalar and object types specific to the Neo4j database.

Int

One of the default GraphQL scalar types. Supports up to 53-bit values - see BigInt for 64-bit value support.

Float

One of the default GraphQL scalar types.

String

One of the default GraphQL scalar types.

Boolean

One of the default GraphQL scalar types.

ID

One of the default GraphQL scalar types. Stored as a string in the database and always returned as a string.

BigInt

Supports up to 64 bit integers, serialized as strings in variables and in data responses. Shares the same Numerical operators as the other numeric types.

type File {
    size: BigInt
}

Can be passed as a number (does not need quotes) when used directly in a query or mutation:

query {
    files(where: { size: 9223372036854775807 }) {
        size
    }
}

Temporal Types

DateTime

ISO datetime string stored as a datetime temporal type.

type User {
    createdAt: DateTime
}

Date

"yyyy-mm-dd" date string stored as a date temporal type.

type Movie {
    releaseDate: Date
}

LocalDateTime

"YYYY-MM-DDTHH:MM:SS" datetime string stored as a LocalDateTime temporal type.

type Movie {
    nextShowing: LocalDateTime
}

Time

RFC3339 time string stored as a Time temporal type.

type Movie {
    nextShowing: Time
}

LocalTime

"HH:MM:SS[.sss+]" time string stored as a LocalTime temporal type.

type Movie {
    nextShowing: LocalTime
}

Spatial Types

Neo4j GraphQL spatial types translate to spatial values stored using point in the database. The use of either of these types in a GraphQL schema will automatically introduce the types needed to run queries and mutations relevant to these spatial types.

Point

The Point type is used to describe the two Geographic coordinate reference systems supported by Neo4j.

In order to use it in your schema, you quite simply add a field with a type Point to any type or types in schema, like the following:

type TypeWithPoint {
    location: Point!
}

Once this has been done, the Point type will be automatically added to your schema, in addition to all of the input and output types you will need to query and manipulate spatial types through your API.

The rest of the documentation under this heading is documenting all of those automatically generated types and how to use them.

Type definition

type Point {
    latitude: Float!
    longitude: Float!
    height: Float
}

Queries and Mutations

Due to the fact that Point is an object type, it has an additional type for input in queries and mutations. However, this input type has the same shape as the object type:

input PointInput {
    latitude: Float!
    longitude: Float!
    height: Float
}
Query

For example, you can query for a User with an exact location:

query Users($longitude: Float!, $latitude: Float!) {
    users(where: { location: { longitude: $longitude, latitude: $latitude } }) {
        name
        location {
            longitude
            latitude
        }
    }
}
Mutation

An example of creating a User with a location is as follows:

mutation CreateUsers($name: String!, $longitude: Float!, $latitude: Float!) {
    createUsers(input: [{ name: $name, location: { longitude: $longitude, latitude: $latitude } }]) {
        users {
            name
            location {
                longitude
                latitude
            }
        }
    }
}

Filtering

In addition to the Numerical operators, the Point type has an additional _DISTANCE filter. All of the filters take the following type as an argument:

input PointDistance {
    point: Point!
    distance: Float!
}

In essence, each of the filters mean the following:

  • _LT: Checks that the specified point field is less than the distance away in meters from the Point being compared against.

  • _LTE: Checks that the specified point field is less than or equal to the distance away in meters from the Point being compared against.

  • _DISTANCE: Checks that the specified point field is the exact distance away in meters from the Point being compared against.

  • _GTE: Checks that the specified point field is greater than the distance away in meters from the Point being compared against.

  • _GT: Checks that the specified point field is greater than or equal to the distance away in meters from the Point being compared against.

In practice, you can construct queries such as the following which will find all users within a 5km (5000m) radius of a Point:

query CloseByUsers($longitude: Float!, $latitude: Float!) {
    users(where: { location_LTE: { point: { longitude: $longitude, latitude: $latitude }, distance: 5000 } }) {
        name
        location {
            longitude
            latitude
        }
    }
}

CartesianPoint

The CartesianPoint type is used to describe the two Cartesian coordinate reference systems supported by Neo4j.

In order to use it in your schema, you quite simply add a field with a type CartesianPoint to any type or types in schema, like the following:

type TypeWithCartesianPoint {
    location: CartesianPoint!
}

Once this has been done, the CartesianPoint type will be automatically added to your schema, in addition to all of the input and output types you will need to query and manipulate spatial types through your API.

The rest of the documentation under this heading is documenting all of those automatically generated types and how to use them.

Type definition

type CartesianPoint {
    x: Float!
    y: Float!
    z: Float
}

Queries and Mutations

Due to the fact that CartesianPoint is an object type, it has an additional type for input in queries and mutations. However, this input type has the same shape as the object type:

input CartesianPointInput {
    x: Float!
    y: Float!
    z: Float
}

Filtering

In addition to the Numerical operators, the CartesianPoint type has an additional _DISTANCE filter. All of the filters take the following type as an argument:

input CartesianPointDistance {
    point: CartesianPoint!
    distance: Float!
}

In essence, each of the filters mean the following:

  • _LT: Checks that the specified point field is less than the distance away from the CartesianPoint being compared against, in the units used to specify the points.

  • _LTE: Checks that the specified point field is less than or equal to the distance away from the CartesianPoint being compared against, in the units used to specify the points.

  • _DISTANCE: Checks that the specified point field is the exact distance away from the CartesianPoint being compared against, in the units used to specify the points.

  • _GTE: Checks that the specified point field is greater than the distance away from the CartesianPoint being compared against, in the units used to specify the points.

  • _GT: Checks that the specified point field is greater than or equal to the distance away from the CartesianPoint being compared against, in the units used to specify the points.