Relay Compatibility

This is the documentation of the GraphQL Library version 6. For the long-term support (LTS) version 5, refer to GraphQL Library version 5 LTS.

The Relay GraphQL Server Specification states that in order for a server to be compatible with Relay, it must provide:

  1. A mechanism for refetching an object.

  2. A description of how to page through connections.

The Neo4j GraphQL Library provides a description of how to page through connections out of the box. However, configuration is required for it to provide a mechanism for refetching an object, which this page details.

Object identification

In order for a Relay client to be able to refetch objects, each type must have a unique object identifier which can be used for this purpose. A server then informs a Relay client that this requirement has been satisfied by having types that implement the Node directive, which has the following definition:

interface Node {
  id: ID!
}

So for example, a type Book might have the definition:

type Book implements Node @node {
  id: ID!
  isbn: String!
}

With that, Relay clients are able to refetch Book objects using the node query field. The following section dives into how to do this with the Neo4j GraphQL Library.

@relayId

The Neo4j GraphQL Library provides an abstraction over the required id field, allowing the value of any unique property in the database to be used as the object identifier. This is provided by the @relayId directive

Definition

The @relayId directive has the following definition:

directive @relayId on FIELD_DEFINITION

Usage

For books, the ISBN usually is a unique identifier:

type Book @node {
  isbn: String! @relayId
}

When the schema is augmented, this type is output as:

type Book implements Node @node {
  id: ID!
  isbn: String!
}

When the id field is used, isbn is the underlying property that is used in the database. Also, the Book type is now refetchable via the node query field, and is ready to be used with a Relay client.

The @relayId directive does not guarantee uniqueness. You should configure a unique node property constraint using the @unique directive.